app.yaml

This section explains how to set up the app.yaml configuration file, which is crucial for the basic startup process as it contains essential settings needed to run aqishare successfully, such as the license key, tracing and logging. While most parameters are optional and adjustable based on your needs, some are critical for proper operation.

Parameter Overview

The table highlights all available top-level properties in the app.yaml that can be used to set up aqishare. For details, refer to the related property explanations in the next section.

Parameter	Mandatory	Type	Default	Description
aqishareLicense	Yes	string		Containts the license key to run aqishare. Refer to License Key below.
redis	Yes	Object		Specifies the Redis database connection required for the queue. Refer to Redis Database below.
collectorPriority	No	number	1	Drives the priority of the collectors queue. Refer to Collector Priority below.
concurrency	No	number	10	Maximum number of tasks that can be processed simultaneously. Refer to Concurrency below.
logging	No	Object		Specify the logging behavior, including log output, format, and other properties like log levels for monitoring and troubleshooting. Refer to Logging below.
metrics	No	Object		Collect metrics for the open-source monitoring and alerting Prometheus. Refer to Metrics below.
port	No	number	3001	The port of aqishare to trigger a collector task manually. Refer to Port below.
privateKeyPath	No	string		The use of encrypted passwords necessitates a private key. This parameter points to the key within the container. Refer to Metrics below.

Parameter in Detail

The parameter from the table above explained in detail.

License Key

The most crucial setting in the app.yaml is the license key. This key should be stored under the aqishareLicense property of the file. If there is no license key, or if the provided license key is invalid or expired, aqishare will run in demo mode. In any case, no Tasks will be executed against the SAP system.

Example

aqishareLicense: 12345-67890-09876-54321

Redis Database

As the queue is based on the open-source database Redis, many additional settings regarding database configuration are available. As a full-featured Redis client, aqishare uses ioredis. For a full list of available parameters, please refer to the ioredis documentation.

Example

redis:
  type: client
  address: redis:6379

Below are some of the most important properties that influence Redis behavior:

Redis Client

Parameter	Mandatory	Description
type	Yes	In this case use client.
address	Yes	IP-address of the Redis container with port number.
network	No	Specifies the network type, either tcp or unix. Default: tcp
username	No	User to login to the database.
password	No	Password to login to the database. Must match the password specified in the requirepass server configuration option.
db	No	Database to be selected after connecting to the server. Default: 1
dialTimeout	No	Dial timeout for establishing new connections. Time-based format such as 3m or 1h. Default: 5s
readTimeout	No	Read timeout for socket reads. If reached, commands will fail with a timeout instead of blocking. Time-based format such as 3m or 1h. Default: 3s
writeTimeout	No	Write timeout for socket writes. If reached, commands will fail with a timeout instead of blocking. Time-based format such as 3m or 1h.
poolSize	No	Maximum number of socket connections. Default: 10

Redis Cluster

Use the following settings to scale Redis horizontally with Redis Cluster.

Parameter	Mandatory	Description
type	Yes	To specify setting for Redis cluster, set the value to: cluster.
addresses	Yes	Array of IP addresses of the Redis cluster with port numbers.
network	No	Specifies the network type, either tcp or unix. Default: tcp
username	No	User to login to the database.
password	No	Password to login to the database. Must match the password specified in the requirepass server configuration option.
dialTimeout	No	Dial timeout for establishing new connections. Time-based format such as 3m or 1h. Default: 5s
readTimeout	No	Read timeout for socket reads. If reached, commands will fail with a timeout instead of blocking. Time-based format such as 3m or 1h. Default: 3s
writeTimeout	No	Write timeout for socket writes. If reached, commands will fail with a timeout instead of blocking. Time-based format such as 3m or 1h.

Redis Sentinel

Use the following Redis Sentinal settings to run Redis with high availability when not using Redis Cluster above.

Parameter	Mandatory	Description
type	Yes	in this case cluster.
addresses	Yes	Array of IP-addresses of the Redis cluster with port numbers.
masterName	No	Master name
sentinelPassword	No	Password to login
username	No	User to login to the database.
password	No	Password to login to the database. Must match the password specified in the requirepass server configuration option.
db	No	Database to be selected after connecting to the server. Default: 1
dialTimeout	No	Dial timeout for establishing new connections. Time-based format such as 3m or 1h. Default: 5s
readTimeout	No	Read timeout for socket reads. If reached, commands will fail with a timeout instead of blocking. Time-based format such as 3m or 1h. Default: 3s
writeTimeout	No	Write timeout for socket writes. If reached, commands will fail with a timeout instead of blocking. Time-based format such as 3m or 1h.
poolSize	No	Maximum number of socket connections. Default: 10

Collector Priority

Change the priority of the collector's queue relative to all other queues.

Example

collectorPriority: 1

Concurrency

Specifies the maximum number of tasks that can be processed simultaneously.

Example

concurrency: 10

Logging

Logging is essential for gaining visibility into the application's operation, enabling effective diagnosis of issues and monitoring of performance. This section explains how to configure and control logging behavior and log output in aqishare.

Example

logging:
  level: info
  caller: false
  structured: true
  timeFormat: 2006-01-02T15:04:05Z07:00
  fieldName: 
    timestamp: time
    level: level
    caller: caller
    message: message
    error: error

Below is a detailed explanation of all the parameters for the logging section used in the example above.

Parameter	Mandatory	Type	Default	Description
level	No	string	info	Specify the log level to control the granularity of information captured in the logs. Available log levels: trace debug info (default) warn error fatal panic disabled (used to disable the logging)
caller	No	boolean	false	This logs the affected source, providing a detailed record that can help in troubleshooting and understanding the context of operations.
structured	No	boolean	true	Formats the log output using JSON syntax, which enhances readability and facilitates easier integration with log management tools.
timeFormat	No	string	2006-01-02T15:04:05Z07:00	Specifies the format used to display the timestamp in log outputs. Refer to Timeformat Reference.
fieldname	No	Object		Object to override default names. Refer below to Specify Parameter fieldname.

Specify Parameter fieldname

There may be situations where it's necessary to modify the default field names in the log output to align with organizational standards. This can help facilitate easier integration with log management tools and ensure consistency across reporting systems. The following field names can be overridden:

Parameter	Mandatory	Type	Default	Description
timestamp	No	string	timestamp	Override the timestamp field name according to your needs to specify the name through which the timestamp value can be accessed.
level	No	string	level	Override the level field name according to your needs to specify the name through which the value can be accessed.
caller	No	string	caller	Override the caller field name according to your needs to specify the name through which the value can be accessed.
message	No	string	message	SOverride the message field name according to your needs to specify the name through which the message value can be accessed.
error	No	string	error	Override the error field name according to your needs to specify the name through which the error value can be accessed.

Metrics

It's possible to gain insights into the HTTP traffic that is directed through aqishare. For this, the interface can expose an endpoint for the open-source monitoring and alerting toolkit Prometheus. To make this endpoint available, specify the following parameter for key metrics in the app.yaml.
To use the metrics, refer to Content Property in either RFC Mapping or Rest Mapping in the configuration section.

Parameter	Mandatory	Type	Default	Description
enabled	No	Boolean	false	By default, the endpoint for Prometheus is disabled. Enable it by setting this parameter to true.
path	No	string	/metrics	The name of the endpoint that is accessible by Prometheus. Make sure the path always starts with a slash!
port	No	number	9090	The port number where the endpoint for Prometheus is accessible.

tip

To visualize the data collected by Prometheus, Grafana can be used, for instance.

warning

Neither Prometheus nor Grafana are part of the aqishare delivery. If you want to use them, you must install and set up them by your own. With the settings above, only the endpoint with the structure required by Prometheus is exposed.

Port

Override the default port used to manually trigger a task in the /tasks/ folder.

tip

For details how to trigger a task manually, refer to Manually trigger a Task using an accessToken.

Example

port: 3001

Password Encryption

Using encrypted passwords requires specifying the privateKeyPath parameter. The value should indicate the path to the private key within the container, which is used to decrypt the passwords. The private key must be either mapped to the container or copied into the image in advance. If password encryption is not needed, this setting can be omitted. The encryption utilizes the RSA mechanism.

tip

For details on generating key pairs and setting up password encryption, refer to chapter Password Encryption in the Configuration section.

Example

privateKeyPath: /app/configs/privateKey.pem

Example Configuration

This is a sample configuration that includes the most relevant properties as explained above. These properties must be present in the app.yaml file.

Example

aqishareLicense: 12345-67890-09876-54321
redis:
  type: client
  address: redis:6379
collectorPriority: 1
concurrency: 10
logging:
  level: info
  caller: false
  structured: true
  timeFormat: 2006-01-02T15:04:05Z07:00
  fieldName: 
    timestamp: time
    level: level
    caller: caller
    message: message
    error: error
metrics:
  enabled: true
  path: /metrics
  port: 9090
port: 3001
privateKeyPath: /app/configs/privateKey.pem