Skip to content

Settings in LUNA Configurator service#

The LUNA Configurator service stores general settings for:

See "Use FaceStream with LUNA Configurator" for details on how the LUNA Configurator service interacts with FaceStream.

FaceStream settings#

Settings configuration is performed by editing parameters in the "FACE_STREAM_CONFIG" section in the Configurator service (see "Use FaceStream with Configurator");

You can also setting up FaceStream by editing the configuration file "fs3Config.conf" in the mode of working without the Configurator service (see "Use FaceStream with configuration files").

Below are the settings divided into logical blocks depending on the main functions performed by the block.

logging#

Settings section of the application logging process. It is responsible for message output on errors and/or current state of the application.

severity#

Severity parameter defines which information the user receives in logs. There are three information filter options:

0 — Outputs all the information 1 — Outputs system warnings only 2 — Outputs errors only

tags#

Tags enable you to get information about the processing of frames and errors that occur only for FaceStream processes of interest.

This parameter enables you to list tags that are associated with logging of relevant information. If a corresponding tag is not specified, the information is not logged.

Information on specified tags is displayed according to the severity parameter value.

Logs text includes the corresponding tag. It can be used for logs filtration.

Errors are always written in the log. They do not require additional tags.

Tags description

Tag Description
streams Information about LUNA Streams operation.
common General information.
ffmpeg Information about FFMPEG library operation.
liveness Information about the presence of a living person in the frame ("liveness" section): is there enough information for liveness check, and does the frame pass the liveness check.
primary-track Information about the primary track ("primary_track_policy" section): the frame passed the specified thresholds and what track is selected as primary.
bestshot Information about the best shot selection: best shot occurrence, its change and sending to external service.
angles Information about filtration by head pose.
ags Information corresponding to the frames quality. The information is used for further processing using LUNA PLATFORM.
mouth-occlusion Information about mouth occlusion is recorded to the log file.
statistics Information about performance, the number of frames processed per second, and the number of frames skipped.
http_api Information about API requests sent to FaceStream in server mode and received responses.
client Information about sending messages to LUNA PLATFORM and the responses received.
json Information about processing parameters from configuration files and the Configurator service.
debug Debug information. It is recommended to use this tag when debugging only and not during FS operation. It provides a large amount of debugging information.
estimator Information about the statistics of completed estimations.

Tag "estimator"

When the "estimator" tag is enabled, FaceStream logs return information on the size of the butches with which the estimators were called. Example of log content with the "estimator" tag enabled:

[I0609 15:48:03.779697    65 EstimatorStatistic.cpp:85] [estimator] Batch statistic for estimator HeadPoseEstimator
Total calls: 1311 total time: 191 ms.
sz  cnt
1   1311 (100.00%)
2   0 (0.00%)
3   0 (0.00%)
...
16  0 (0.00%)

In this case, the statistics show the following:

  • Total of 1311 calls were made to the "HeadPoseEstimator" estimator, which took 191 milliseconds.
  • All calls (1311) were processed individually, each in its own batch of size 1.
  • Batch sizes from 2 to 16 were not used.

If the estimators were not called, then no information will be output in the FaceStream logs.

mode#

Mode parameter sets the logging mode of the application: file or console. There are three modes available:

  • "l2c" – Output information to console only
  • "l2f" – Output information to file only
  • "l2b" – Output to both, console and file

In the FaceStream mode of working with configuration files, you can configure the directory to save logs when information is output to a file using the --log-dir launching parameter.

sending#

This section is used to send portraits in the form of HTTP-requests from FaceStream to external services.

request_type#

This parameter is used only for working with faces.

This parameter defines a type of query that is used to send portraits to external services. There are 2 supported types (to work with different versions of LUNA):

  • "jpeg" is used to send normalized images to VisionLabs LUNA PLATFORM.
  • "json" may be used to send portraits to custom user services for further image processing.

For a detailed description of the requests, see the table below.

Request types

Format Request type Authorization headers Body
JSON PUT Authorization: Basic, login/password(Base64) Media type: application/json; frame – the original frame in Base64 (if send_source_frame option is on); data – a portrait in Base64; identification – Cid parameter value. JSON example: {frame":"","data":"image_in_base_64","identification":"camera_1"}
JPEG POST Authorization: Basic, login/password(Base64) or X-Auth-Token: 11c59254-e83f-41a3-b0eb-28fae998f271(UUID4) Media type: image/jpeg

request_timeout_ms#

This parameter sets the timeout for sending and receiving events from/to the LUNA PLATFORM in milliseconds.

The default value is 30 seconds (30,000 milliseconds).

portrait_type#

This parameter is used only for working with faces.

This parameter defines the format of a detected face to send to an external service. Possible values:

  • "warp" — Use a normalized image.
  • "gost" — Do not use the transformation, cut the detected area from the source frame, considering indentation.
  • "crop" – Use an area expanded and cropped around the detected object.

Warp format

Properties of the normalized image (warp):

  • Size of 250x250 pixels.
  • Face is centered.
  • Face should be aligned in the way that, if you draw an imaginary line connecting the corners of the eyes, it is close to horizontal.

Such image format when working with LUNA PLATFORM offers the following advantages:

  • Constant minimal predictable amount of data for network transfer;
  • Face detecting phases in LUNA PLATFORM automatically turn off for such images, which leads to the significant reduction of interaction time.

Crop format

A Crop image is a fragment of an image obtained by expanding and cropping the area around the detected object. The expansion of the area is determined by the new "sending" > "crop_factor" parameter, which increases the dimensions of the original rectangle containing the object. The maximum size of the cropped image is controlled by the new "sending" > "max_crop_size" parameter, which limits the largest side of the area. If the size of the fragment exceeds the specified parameter, the fragment will be scaled proportionally along both coordinates to the desired size. A Crop image allows capturing more context and detail around the object compared to a sample.

This allows for more flexible image processing. Sending Crop images has several key advantages:

  • Along with the Crop image, the coordinates of the face on both the Crop image and the source image are transmitted. This avoids the need to use redetetor, ensuring the presence of the face in the image and saving computational resources.
  • A Crop image contains more context and details around the face, allowing for the estimation of various parameters that cannot be estimated on a biometric. For example, Deepfake estimation, Liveness estimation, etc., can be performed with greater accuracy.
  • External services and face recognition algorithms often work better with Crop images than with samples. This is because Crop images contain more information and context, improving the accuracy of recognition and analysis.

crop_factor#

The factor to increase the size of the original rectangle containing the object.

This parameter determines how much wider and taller the crop area will be compared to the original size. For example, with a "crop_factor" of 2.2, the crop area will be enlarged to 2.2 times its original size. This allows you to capture more context around the detected object.

max_crop_size#

Maximum size of cropped image.

This parameter limits the largest side of the crop area to no larger than a specified value. If the cropped image exceeds "max_crop_size", it will be scaled to a valid size while maintaining aspect ratio. This ensures that the cropped images are not too large and remain within the specified dimensions.

send_source_frame#

This parameter enables to send a full source frame where the face was detected.

The source frame can be saved both in the bucket of the LUNA Image Store service and in the "/images" resource of the LUNA API service. The method of saving the source frame is set by specifying the appropriate address in the "frame_store" parameter.

For the collection of best shots ("face_bestshots_to_send" > 1), only one source frame is sent, which is determined by FaceStream to be the best of all best shots. For example, if the setting value "number_of_bestshots_to_send" is 3, then three best shots will be sent to LP and only one source frame, which will be automatically selected from the three best shots.

If the source frame is supposed to be saved to the LUNA Image Store service bucket, then the frame will be sent to the LP some time before the best shot is sent. First, it is saved in the LUNA Events database and assigned a unique ID, which is stored in the "image_origin" field of the "face_detect_result"/"body_detect_result" table. Next, the best shot is sent to the LP and an event is generated, where the "image_origin" field indicates the ID of the source frame taken from the LUNA Events database.

Example from the response body of the event about successful saving to the bucket:

"events": [
    detections": [
        "image_origin": "/1/buckets/source-images/images/83c383d8-8af4-406c-8ff8-76eb389e61c8"

If the source frame is supposed to be saved to the "/images" resource, then the frame will be sent along with the best shot using the "multipart/form-data" scheme of the request to generate the LUNA PLATFORM event.

Example from the response body of the event about successful saving to the "/images" resource of the LUNA API service:

"events": [
    detections": [
        "image_origin": "/6/images/19c5c40a-04e4-4f2b-811c-0f3bb0003359"

If the "image_origin" field contains an address like "/6/samples/faces/c93f39f1-809c-4583-b386-c166cecac333", it signifies the location for storing the best shot rather than the source image.

size_source_frame#

Parameter changes the width of the source frame to the specified value. Valid range is [0...1024]. The value "0" means that the width will not change. The fractional part of the input is affected.

FaceStream sends the "X-Luna-Meta-rescale" header to the LUNA PLATFORM, which contains the scaling factor of the source image in the form of a floating-point number.

The scaling factor enables calculating the real coordinates of the scaled source image. To do this, divide the size of the obtained image by the obtained scaling factor.

Note. The real size is calculated with an absolute error of less than 1 / (2 * scaling factor).

For example, if the obtained image has a size of 200x113, and the scaling factor is 0.104399, then the real size of the source image is 1916x1082 (200/0.104399=1916, 113/0.104399=1082).

The scaling factor can be found in LUNA PLATFORM:

  • In the response header to the "get image" request to the LUNA API service. The request must be made with the "with_meta = 1" query parameter.
  • In the "image_id.meta.json" file located next to the source image in the LUNA Image Store bucket of source images.

The "X-Luna-Meta-rescale" header is only sent if sending the source frame is enabled (parameter "send_source_frame = 1"). The LUNA PLATFORM handler should also have a policy of saving the source image.

If scaling is not set for the source frame (parameter "size_source_frame = 0"), then the value of the "X-Luna-Meta-rescale" response header will be equal to 1.

detection_path_length#

This parameter is used only for working with bodies.

Parameter sets the maximum number of detections for the "minimal_body_track_length_to_send" parameter. Values from 1 to 100 inclusive are available.

The maximum number of detections cannot exceed 100. If there are more than 100 detections, then the FaceStream algorithm will remove unnecessary detections with some step.

minimal_body_track_length_to_send#

This parameter is used only for working with bodies.

This parameter enables you to send a specified number of detections with the coordinates of the human body — x, y, width and height along with the best shots (see the "save event" request in the LUNA PLATFORM OpenAPI document). According to the sets of detections of the human body, it is possible to determine its path.

The detection with the best shot is mandatory to be sent.

Sending detections
Sending detections

If the number of detections is less than the specified value, then these detections will not be sent. For example, if the number of detections is "3" and the value of "minimal_body_track_length_to_send" is "4", then no detections will be sent and the following message will be displayed in the FaceStream logs:

Track is too short and will not be sent. Length 3 < 4

If the parameter value is "0", then the number of detections will be equal to the number of best shots.

async_requests#

The parameter specifies whether to execute requests asynchronously or synchronously in LUNA PLATFORM.

By default, the asynchronous mode is set, in which all requests to the LUNA PLATFORM are performed in parallel.

aggregate_attr_requests#

This parameter enables the best shots aggregation to receive a single descriptor in LUNA PLATFORM.

Aggregation is performed if there is more than one best shot sent. The number of frames to send is set by the "face_bestshots_to_send" or "body_bestshots_to_send" parameter.

The accuracy of face and body recognition is higher when using an aggregated descriptor.

jpeg_quality_level#

JPEG quality for source frames sending:

  • "best" — Compression is not performed.
  • "good" — 75% of source quality.
  • "normal" — 50% of source quality.
  • "average" — 25% of source quality.
  • "bad" — 10% of source quality.

The "best" quality is set by default.

High quality images sending can affect the frames processing speed.

lunaplatform#

This section describes the settings for connecting to LUNA PLATFORM (API service) for subsequent processing of data sent by FaceStream.

origin#

The address and port of the server where the LUNA API service is running.

api_version#

The parameter specifies the API version of the LUNA API service. At the moment, the API version "6" is supported.

lunastreams#

This section describes how to send ready-made images as HTTP requests from FaceStream to the LUNA Streams service.

See "Interaction of FaceStream with LUNA Streams" section for details on how LUNA Streams works with FaceStream.

origin#

The address and port of the server where the LUNA Streams service is running.

api_version#

The parameter specifies the version of the LUNA Streams service API. Currently, two API versions are supported - "1" and "2".

The default version is "1".

The current version of the API can always be found in the LUNA Streams service documentation.

max_number_streams#

The parameter sets the upper bound on the number of streams. The value must be greater than 0.

request_stream_period#

The parameter sets the time period between requests to receive new streams from LUNA Streams in the range from 0.1 to 3600 seconds.

The default value is 1 second.

send_feedback_period#

The parameter sets the time period between sending reports on processed streams to LUNA Streams in the range from 1.0 to 3600 seconds.

The default value is 5 seconds.

The value of this parameter should not exceed the value of the "STREAM_STATUS_OBSOLETING_PERIOD" parameter, set in the LUNA Streams service settings.

max_feedback_delay#

The parameter sets the maximum report sending delay in the range from 1.0 to 3600 seconds. If the report has not been sent within the given time, then FaceStream will stop processing the current streams.

The default value is 10 seconds.

The value of this parameter should not be less than the value of the parameter "send_feedback_period" and should not exceed the value of the parameter "STREAM_STATUS_OBSOLETING_PERIOD", set in the LUNA Streams service settings.

performance#

stream_images_buffer_max_size#

The parameter specifies the maximum size of buffer with images for a single stream.

When you increase the parameter value, the FaceStream performance increases. The higher is the value, the more memory is required.

We recommend setting this parameter to 40 when working with GPU, if there is enough GPU memory.

enable_gpu_processing#

This parameter enables you to utilize GPU instead of CPU for calculations.

GPU enables you to speed up calculations, but it increases the consumption of RAM.

GPU calculations are supported for FaceDetV3 only. See "defaultDetectorType" parameter in the FaceEngine configuration ("faceengine.conf").

convert_full_frame#

If this parameter is enabled, the frame is immediately converted to an RGB image of the required size after decoding. This results in a better image quality but reduces the speed of frames processing.

If this parameter is disabled, the image is scaled according to the settings in the TrackEngine configuration (standard behavior for releases 3.2.4 and earlier).

This parameter is similar to frame_processing_mode parameter, but it is set for all FaceStream instances at once.

fps_floor#

This parameter is intended to control the number of frames analyzed in the video stream, which enables you to reduce the load on the system by skipping some frames. This can be useful when you need to reduce the requirements for computing resources while maintaining acceptable analysis accuracy.

The number of skipped frames is calculated as the difference between the frame rate of the video stream and the "fps_floor" value. The skipped frames are distributed evenly over each second.

If the "fps_floor" value is zero or negative, FaceStream will ignore the setting, and the number of frames processed will remain unchanged.

For example, with "fps_floor" = 15 for a video stream with a frequency of 25 fps, FaceStream will skip 10 frames per second (25 - 15). These 10 frames will be evenly distributed over time to maintain the integrity of video playback and avoid sharp jumps.

monitoring#

Monitoring settings are set in this section.

storage_type#

This parameter enables to select the type of data storage for monitoring. For now, only the Influx database can be used.

send_data#

This parameter enables sending monitoring. Disabled by default.

organization#

This parameter specifies the InfluxDB 2.x workspace.

The workspace is created by passing the corresponding argument at the start of the InfluxDB container.

bucket#

This parameter sets the InfluxDB 2.x bucket.

The bucket is created by passing the corresponding argument at the start of the InfluxDB container. It can be also created using the Influx UI.

token#

This parameter specifies the InfluxDB 2.x authentication token.

The token is created by passing the corresponding argument at the start of the InfluxDB container.

origin#

This parameter specifies the IP address and port of the server with InfluxDB 2.x.

The default address is "127.0.0.1". Such an address means that InfluxDB 2.x, located on a server with LUNA Configurator, will be used. If InfluxDB 2.x is located on a different server, then in this parameter you need to specify the correct IP address of InfluxDB 2.x.

"origin": "http://127.0.0.1:8086/"

flushing_period#

This parameter sets frequency of sending monitoring data to InfluxDB (in seconds).

The default is 1 second.

TrackEngine settings#

This section describes the parameters of the TrackEngine configuration file that are used to configure FaceStream.

Settings configuration is performed by editing parameters in the "TRACK_ENGINE_CONFIG" configuration in the Configurator service (see "Use FaceStream with Configurator");

You can also setting up TrackEngine by editing the configuration file "trackengine.conf" in the mode of operation without the Configurator service (see "Use FaceStream with configuration files").

use-face-detector and use-body-detector#

These parameters allow you to enable or disable detection of faces and bodies. You can enable simultaneous detection.

See "Face and body detection collaborative mode" for details.

It should be remembered that in order to successfully change the detection, it is necessary to set the appropriate FaceStream settings and settings of stream sources.

<!-- use-face-detector: Flag to use or not face detection -->
<param name="use-face-detector" type="Value::Int1" x="1" />

<!-- use-body-detector: Flag to use or not body detection -->
<param name="use-body-detector" type="Value::Int1" x="0" />

detector-step#

The "detector-step" parameter enables you to specify the number of frames on which face redetection will be performed in the specified area before face detection is performed. Redetection requires fewer resources, but the face may be lost if you set a large number of frames for redetection.

<!-- detector-step: The count of frames between frames with full detection, [0 .. 30] ('7' by default). -->
<param name="detector-step" type="Value::Int1" x="7" />

detector-scaling#

The "detector-scaling" parameter enables you to scale the frame before processing. The frame size for scaling is set in the parameter "scale-result-size".

For more information about scaling, see "Frame scaling".

<!-- detector-scaling: Scale frame before detection for performance reasons, [0, 1] ('0' by default). -->
<param name="detector-scaling" type="Value::Int1" x="0" />

scale-result-size#

The "scale-result-size" parameter sets the maximum frame size after scaling the largest side of the frame.

To use this parameter, you must enable the "detector-scaling" parameter.

If the source frame had a size of 1920x1080 and the value of "scale-result-size" is equal to 640, then FaceStream will process the frame of 640x360 size.

If the frame was cut out using the "roi" parameter, the scaling will be applied to this cropped frame. In this case, you should specify the "scale-result-size" parameter value according to the greater ROI side.

You should gradually scale the frame and check whether face or body detection occurs on the frame, to select the optimal "scale-result-size" value. You should set the minimum image size at which all objects in the area of interest are detected.

Further extending our example, images below depict a video frame without resize (at original 1920x1080 resolution) and after resize to 960x640 with face detections visualized as bounding boxes.

Six faces can be detected when the source image resolution is 1920x1080.

Detections in image 1920X1080
Detections in image 1920X1080

Three faces are detected after the image is scaled to the 960x640 resolution. The faces in the background are smaller in size and are of poor quality.

Detections in image 960X640
Detections in image 960X640

The smaller the frame resolution, the less resources are consumed.

When working with bodies, this parameter works the same way.

<!-- scale-result-size: If scaling is enable, frame will be scaled to this size in pixels (by the max dimension — width or height). 
Upper scaling is not possible. ('640 by default') -->
<param name="scale-result-size" type="Value::Int1" x="640" />

skip-frames#

This parameter is used only for working with faces.

The "skip-frames" parameter sets the number of frames during which the system will wait for the object to reappear in the area where it disappeared.

Note that very high values may lead to performance degradation.

<!-- skip-frames: If track wasn't updated by detect/redetect for this number of frames, then track is finished ('36' by default). -->
<!-- note: very high values may lead to performance degradation. Parameter doesn't affect on human tracking. -->
<param name="skip-frames" type="Value::Int1" x="36" />

frg-subtractor#

When the "frg-subtractor" parameter is enabled, motion in the frame is considered. The following face and body detection will be performed in the area with motion, not in the entire frame.

The areas with motion are determined after the frame is scaled.

When the "frg-subtractor" is enabled, the performance of FaceStream is increased.

<!-- frg-subtractor: Use foreground subtractor for filter of frames, [0, 1] ('1' by default). -->
<param name="frg-subtractor" type="Value::Int1" x="1" />

frg-regions-alignment#

The "frg-regions-alignment" parameter enables you to set the alignment for the area with motion.

<!-- frg-regions-alignment: frg regions alignment. Useful for detector better batching utilization. -->
<!-- 0 or negative values mean using non aligned regions, (0 by default). -->
<param name="frg-regions-alignment" type="Value::Int1" x="0" />

frg-regions-square-alignment#

When the "frg-regions-square-alignment" parameter is enabled, the width and height of the area with motion will always be equal.

<!-- align frg regions to rect with equal sides (max side choosen). See frg-regions-alignment, [0, 1] ('1' by default). -->
<param name="frg-regions-square-alignment" type="Value::Int1" x="1" />

batched-processing#

The "batched-processing" parameter enables batch processing of frames.

When working with several video cameras, a frame is collected from each frame. Then the batch of frames is processed.

When the parameter is disabled, the frames are processed one by one.

When using batch processing mode, the delay before processing increases, but the processing itself is faster.

It is recommended to enable the parameter both when using the GPU and when using the CPU.

<!-- batched-processing: Process streams frames in batch or separately, [0, 1] ('1' by default). -->
<param name="batched-processing" type="Value::Int1" x="1" />

min-frames-batch-size#

The "min-frames-batch-size" parameter sets the minimal number of frames collected from all the cameras before processing.

It is recommended to set the "min-frames-batch-size" parameter value equal to the number of streams when using the GPU.

It is recommended to set the "min-frames-batch-size" parameter value equal to "2" when using the CPU.

<!-- min-frames-batch-size: stream frames min batch size value to process, ('0' by default). -->
<!-- higher values lead to higher processing latency but increase throughput and device utilization. -->
<!-- zero/negative values disable this feature, so any stream frames will be processed if they are available -->
<!-- note: this parameter should be regulated with 'max-frames-batch-gather-timeout' (see below) -->
<param name="min-frames-batch-size" type="Value::Int1" x="0" />

max-frames-batch-gather-timeout#

The "max-frames-batch-gather-timeout" parameter specifies the time between processing of the batches.

If a single frame is processed within the specified time and there is an additional time margin, FaceStream waits for additional frames to increase GPU utilization.

If the "max-frames-batch-gather-timeout" parameter is set to "20", this time is used to process the previous batch and collect a new one. After 20 seconds, the processing begins even if the number of frames equal to "min-frames-batch-size" was not collected. Processing of the next batch cannot begin before the processing of the previous one is finished.

There is no timeout for collecting frames to the batch if the parameter is set to "0" and "min-frames-batch-size" is ignored.

It is recommended to set the "max-frames-batch-gather-timeout" parameter value equal to "0" both when using the GPU and when using the CPU.

<!-- max-frames-batch-gather-timeout: max available timeout to gather next stream frames batch (see 'min-frames-batch-size') from last processing begin time point (measured in ms), ('-1' by default). -->
<!-- negative values disable this feature (no timeout, so only stream frames batches with size no less than 'min-frames-batch-size' value will be processed) -->
<!-- note: this parameter is complementary to 'min-frames-batch-size' and controls min average fps of stream frames batches processing -->
<param name="max-frames-batch-gather-timeout" type="Value::Int1" x="-1" />

LUNA Streams settings#

This section describes the parameters of the LUNA Streams service that are set in the LUNA Configurator service.

LUNA_STREAMS_DB#

db_type#

The parameter sets the type of database used. The following types are available:

  • "postgres" — PostgreSQL database type
  • "oracle" — Oracle database type

Setting format: string.

Default value: postgres.

db_host#

The parameter sets the IP address of the server with the LUNA Streams database.

The default address is "127.0.0.1". This address means that the LUNA Streams database located on the server with LUNA Configurator will be used. If the database is located on another server, then in this parameter you should specify the correct IP address of the server with the database.

Setting format: string.

Default value: 127.0.0.1.

db_port#

The parameter sets LUNA Streams database listener port.

The default port for "postgres" type is "5432".

The default port for "oracle" type is "1521".

Setting format: string.

Default value: 5432.

db_user#

The parameter sets the database username.

Setting format: string.

Default value: luna.

db_password#

The parameter sets the database password.

Setting format: string.

Default value: luna.

db_name#

The parameter sets the database name for "postgres" and the name of the SID for "oracle" type to connect to.

Setting format: string.

Default value: luna_streams.

db_settings > connection_pool_size#

The parameter sets the database connection pool size.

Setting format: string.

Default value: 10.

dsn#

The parameter sets the DSN connection string for connecting to the database.

Setting format: string.

DSN is a connection string that identifies and points to the data source (database) to which you want to establish a connection.

Settings such as multiple hosts, authentication data, port, and other parameters can be set in the DSN string.

The settings depend on the type of database. Multiple hosts are supported only with PostgreSQL.

By default, the "dsn" parameter is not displayed in the "Settings" tab in the Configurator. You can check the list of all available parameters for a section on the "Limitations" tab.

Below is an example of specifying the "dsn" parameter:

{
"dsn": "luna:luna@postgres01:5432,postgres02:5432/luna_streams?some_option=some_value"
"db_settings": {
    "connection_pool_size": 5
    }
}

Here:

  • "luna:luna" — Username and password for connecting to PostgreSQL.
  • "@postgres01:5432,postgres02:5432" — Comma-separated list of hosts and ports. This means that the service will try to connect to the first host ("postgres01") on port 5432. If this fails, it will try to connect to the second host ("postgres02") also on port 5432.
  • "/luna_streams" — Database of the Streams service.
  • "?some_option=some_value" — Optional parameters for connection.

If necessary, you can combine the DSN string and the classic settings, but the DSN string is a higher priority. You can partially fill in the DSN string (for example, "postgres 01,postgres02/luna_streams"), and then the missing parameters will be filled in from the values of the parameters "db_host", "db_port", "db_name", "db_user" and "db_password".

At startup, the service will create a pool of connections to one of the available DSN hosts. In case of problems with establishing a connection after several unsuccessful attempts, the service will again try to set up a connection pool to any of the available DSN hosts.

LUNA_LICENSES_ADDRESS#

This section sets the settings for connecting to the LUNA Licenses service.

origin#

The parameter sets the protocol, IP address and port of the LUNA Licenses service.

The IP address "127.0.0.1" means that the LUNA Licenses service located on the server with LUNA Configurator will be used. If the service is located on another server, then in this parameter you need to specify the correct IP address of the server running the LUNA Licenses service.

Setting format: string.

Default value: http://127.0.0.1:5120.

api_version#

This parameter sets the API version of the LUNA Licenses service. The available API version is "1".

Setting format: integer.

Default value: 1.

LUNA_STREAMS_LOGGER#

This section sets the logging settings for the LUNA Streams service.

log_level#

The parameter sets the level of debug printing, by priority: "ERROR", "WARNING", "INFO", "DEBUG".

Setting format: string.

Default value: INFO.

log_time#

The parameter sets the time format used in log entries. The following values are available:

  • "LOCAL" — Displays the local time of the system on which the logs are being recorded.
  • "UTC" — Displays Coordinated Universal Time, which is a time standard and is not affected by local time zones or seasonal time changes.

Setting format: string.

Default value: LOCAL.

log_to_stdout#

The parameter enables you to send logs to standard output (stdout).

Setting format: boolean.

Default value: true

log_to_file#

The parameter enables you to save logs to a file. The directory with log files is specified in the "folder_with_logs" parameter.

Setting format: boolean.

Default value: false.

folder_with_logs#

The parameter sets the directory in which logs are stored. The relative path starts from the application directory.

To use this parameter, you must enable the "log_to_file" parameter.

Setting format: string.

Default value: ./

Example:

"folder_with_logs": "/srv/logs"

max_log_file_size#

The parameter sets the maximum size of the log file in MB before performing its rotation (0 — do not use rotation).

To use this parameter, you must enable the "log_to_file" parameter.

Setting format: integer.

Default value: 1024

multiline_stack_trace#

The parameter enables multi-line stack tracing in logs. When the parameter is enabled, information about the call stack is recorded in the logs so that each stack frame is placed on a separate line, which improves readability. If the parameter is disabled, information about the call stack is recorded on one line, which may make logs less convenient for analysis.

Setting format: boolean.

Default value: true.

format#

The parameter defines the format of the output logs. The following values are available:

  • "default" — Standard output format of the LUNA PLATFORM logs.
  • "json" — Output of logs in json format.
  • "ecs" — Output of logs in ECS format (Elastic Common Schema).

When using the "ecs" value, the following fields will be used:

  • "http.response.status_code" — Contains the HTTP response status code (e.g., 200, 404, 500, etc.).
  • "http.response.execution_time" — Contains information about the time taken to execute the request and receive the response.
  • "http.request.method" — Contains the HTTP request method (GET, POST, PUT, etc.).
  • "url.path" — Contains the path in the request's URL.
  • "error.code" — Contains the error code if the request results in an error.

Setting format: string.

Default value: default.

LUNA_MONITORING#

In this section, settings for monitoring LUNA PLATFORM services are set.

For more information about monitoring, see "Monitoring" section.

storage_type#

The storage type for storing monitoring data.

Currently, only the Influx DB is available.

Setting format: string.

Default value: influx.

send_data_for_monitoring#

The parameter enables you to enable or disable sending monitoring data to InfluxDB.

Setting format: integer.

Default value: 1.

use_ssl#

The parameter enables you to use HTTPS to connect to InfluxDB.

Setting format: integer.

Default value: 0.

organization#

The parameter sets InfluxDB 2.x workspace.

Setting format: string.

Default value: luna.

token#

The parameter sets InfluxDB 2.x authentication token.

Setting format: string.

bucket#

The parameter sets InfluxDB 2.x bucket name.

Setting format: string.

Default value: luna_monitoring.

host#

The parameter sets IP address of server with InfluxDB 2.x.

The default address is "127.0.0.1". This address means that InfluxDB 2.x will be used, located on the server with LUNA Configurator. If InfluxDB 2.x is located on a different server, then you should specify the correct InfluxDB 2.x IP address in this parameter.

Setting format: string.

Default value: 127.0.0.1.

port#

The parameter sets InfluxDB 2.x port.

Setting format: string.

Default value: 8086.

flushing_period#

The parameter sets frequency of sending monitoring data to InfluxDB.

Setting format: integer (seconds).

Default value: 1.

LUNA_SERVICE_METRICS section#

This section enables and configures the collection of metrics in the Prometheus format.

For more information about monitoring, see "Monitoring" section.

enabled#

The parameter enables metrics collection.

If metrics collection is disabled, a request to the /metrics resource will return an appropriate message.

Setting format: boolean.

Default value: false.

metrics_format#

The parameter sets the metrics format.

Currently only the Prometheus format is supported.

See the official Prometheus documentation for more details.

Setting format: string.

Default value: prometheus.

extra_labels#

The parameter specifies custom label types.

Setting format: label_name=label_value.

Default value is not set.

LUNA_STREAMS_HTTP_SETTINGS#

This section contains parameters responsible for process HTTP connections. More detail see here.

request_timeout#

The parameter sets the duration of time between the instant when a new open TCP connection is passed to the server, and the instant when the whole HTTP request is received.

Setting format: integer (seconds).

Default value: 60.

response_timeout#

The parameter sets the duration of time between the instant the server passes the HTTP request to the app, and the instant a HTTP response is sent to the client.

Setting format: integer (seconds).

Default value: 600.

request_max_size#

The parameter sets the maximum size of the request.

Setting format: integer (bytes).

Default value: 1073741824.

keep_alive_timeout#

The parameter sets the timeout for maintaining HTTP activity.

Setting format: integer (seconds).

Default value: 15.

LUNA_STREAMS_LOGS_CLEAR_INTERVAL#

This section contains settings for automatic deletion of stream logs.

Automatic log deletion helps clear the "log" table of the LUNA Streams database from a large number of unnecessary logs.

See the detailed description with examples in the section "Streams logs automatic deletion".

active#

The parameter enables or disables automatic deletion of logs.

Setting format: boolean.

Default value: 0.

interval#

The parameter specifies the interval for deleting logs. Logs older than this interval will be deleted.

The interval must be specified in conjunction with interval type. For example, "3" (interval) + day (interval type).

Setting format: integer.

Default value: 7.

interval_type#

The parameter specifies one of the following interval types:

  • "weeks"
  • "days"
  • "hours"
  • "minutes"
  • "seconds"

The interval type must be specified in conjunction with the interval. For example, "3" (interval) + day (interval type).

Setting format: string.

Default value: days.

check_interval#

The parameter specifies the frequency of checking logs for deletion in seconds.

Setting format: integer.

Default value: 180.

Other#

stream_worker_async_lock_timeout#

The parameter sets timeout of the LUNA Streams instance to lock a row in a database table. The value of this setting should be increased if the stream statuses are not updated, which may be due to a slow connection from the service to the database.

Setting format: number (seconds in range (0, 1]).

Default value: 0.1.

stream_status_obsoleting_period#

The parameter sets stream status obsolescence period. For this period of time, the FaceStream worker should transfer the LUNA Streams report. Otherwise, the status of the stream will be changed to "restart", and the belated report will be rejected.

Setting format: number (seconds in range (0, 86400]).

Default value: 20.

luna_streams_active_plugins#

The parameter sets the list of active plugins (see the information about plugins workflow in the LUNA PLATFORM 5 administrator manual).

Setting format: array > string.

Default value: [].

storage_time#

The parameter specifies the time format used for records in the database. The following values are available:

  • "LOCAL" — Displays the local time of the system on which the logs are being recorded.
  • "UTC" — Displays Coordinated Universal Time, which is a time standard and is not affected by local time zones or seasonal time changes.

Setting format: string.

Default value: LOCAL.