Configuration

DetectMateService can be configured using a YAML settings file, environment variables, or CLI flags. The precedence order is:

CLI flags > environment variables > YAML file

Service settings

These settings control the service infrastructure.

Naming components

component_name can be chosen freely, but it is not used as a display label anywhere. Logs, metrics and log file names all use component_id, component_name is only used to seed it.

component_id = uuid5(NAMESPACE_URL, f"detectmate/{component_type}/{component_name}").hex

This means:

• Names must be unique per instance.
• Without a name, uniqueness comes from the address. Two components of the same type sharing one engine_addr collide. Set component_name when you run more than one instance.
• Changing component_type or component_namechanges the id
• component_id can be set explicitly if you need to control it directly

YAML files

You can provide a YAML file containing the service settings. Below is an example settings.yaml:

component_name: "my-detector"
log_level: "DEBUG"
log_dir: "./logs"

# Manager Interface
http_host: 127.0.0.1
http_port: 8000

# Engine Interface (Data Channel)
engine_addr: "ipc:///tmp/detectmate.engine.ipc"
engine_autostart: true

# Output Destinations (where processed data is sent)
out_addr:
  - "tcp://127.0.0.1:5000"
  - "ipc:///tmp/output.ipc"

out_dial_timeout: 1000

Environment variables

Environment variables override values in the YAML file. They are prefixed with DETECTMATE_.

Example:

export DETECTMATE_LOG_LEVEL=DEBUG
export DETECTMATE_COMPONENT_NAME=worker-1
detectmate start

Component configuration

In addition to the service settings (which configure the runner), you can also pass a separate configuration file for the specific component logic (e.g., detector parameters) using the --config flag in the CLI. This file is specific to the implementation of the component you are running.

Component configuration controls the specific logic of the detector or parser. To support dynamic library loading, this file uses a nested structure. The configuration must be namespaced by the component category (detectors or parsers) and the specific class name to allow the library to correctly route parameters. Example detector_config.yaml

detectors:                 # Category Level
  NewValueDetector:        # Class Name Level
    auto_config: false
    method_type: new_value_detector
    params:                # Implementation Specific Level
    events:
        1:
            test:
                params: {}
                variables:
                    - pos: 0
                      name: var1
                      params:
                          threshold: 0.5
                header_variables:
                    - pos: level
                      params: {}

What goes in a the config file

Only the outer layout (i.e. category level, class name level, then the component's own keys) is the same for every component. What is valid inside is defined by the component's configuration class (<ComponentClass>Config, see Config class resolution). There is no single config file that fits all components: a NewValueDetector takes different fields than a MatcherParser, etc. To find the fields a component accepts:

• Library documentation: every parser and detector has its own page listing the fields it accepts, see Library component reference below. Detectors Configuration explains how the library interprets the values.
• The config class itself: the fields, types and defaults of <ComponentClass>Config in the library source are the authoritative list.
• Let the service generate one: point config_file at a path that does not exist yet and the service writes a default file derived from the component's config class on startup. It is a scaffold, not a working config! Values it cannot infer are written as <PLACEHOLDER> and have to be filled in.

You can read more about Components in the Using a Library Component section.

Library component reference

Every parser and detector the library documents and the fields in its config file. Each page also names the class to put in component_type. Some components ship only with an optional extra.

Parsers

Detectors

These tables are auto-generated from the library documentation.

HTTP Admin Interface

The service provides a REST API for runtime management and monitoring.

Authentication

When http_api_key is set, every /admin/* route requires the key in the X-Auth-Token header. A missing or wrong key returns 401 {"detail": "Invalid authentication credentials"}. /metrics, /docs, /redoc and /openapi.json never require a key.

If no key is set, the admin API is open and the service logs a warning at startup.

Generate a key and pass it through the environment rather than the settings YAML, so it isn't committed with the config:

export DETECTMATE_HTTP_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
detectmate --settings settings.yaml

Call the API with the header:

curl -H "X-Auth-Token: $DETECTMATE_HTTP_API_KEY" http://127.0.0.1:8000/admin/status
detectmate-client --api-key "$DETECTMATE_HTTP_API_KEY" status   # or set DETECTMATE_API_KEY

In the Swagger UI (/docs), click Authorize and enter the key.

With Docker Compose, put DETECTMATE_HTTP_API_KEY=<key> in a .env file next to docker-compose.yml. .env is gitignored. The same key is then used by the parser and both detectors.

To rotate the key, change it and restart the service.

The key is sent in cleartext over plain HTTP. Either keep http_host on loopback or a private network, or put a TLS-terminating reverse proxy in front of the service.

Core Endpoints

Persistency Endpoints

These endpoints are available when the loaded library component has persistency configured (via the persist block in its component config).

/admin/persistency/save, /admin/persistency/status, and /admin/persistency/export return 404 if no library component is loaded or if persist is not configured. /admin/persistency/load and /admin/persistency/import additionally return 409 if the engine is running - stop it first with /admin/stop. /admin/persistency/import returns 422 if the uploaded file is not a valid zip or does not contain metadata.json. See usage.md for detectmate-client equivalents.

/admin/persistency/status response

{
  "path": "/state/NewValueDetector",
  "save_interval_seconds": 300,
  "events_until_save": null,
  "auto_load": false,
  "events_seen_count": 12,
  "events_with_data_count": 8,
  "events_since_save": 47,
  "last_saved_at": "2026-06-16T10:30:00+00:00"
}

Training State Endpoints

These endpoints control whether the library component is actively training or configuring its model. They are available whenever a library component is loaded.

Both endpoints return 404 if no library component is loaded. See usage.md for detectmate-client equivalents.

Background: training vs. configuration

Each incoming event is evaluated by the component's fit logic, which decides what to do with it. There are two independent phases:

• Configure: the component learns the structure of the data (e.g. which event types and variables exist). Runs for a fixed number of events set via data_use_configure in the component config.
• Train: the component fits its model on the observed data. Runs for a fixed number of events set via data_use_training.

Both phases stop automatically after their configured event count. By default the component transitions to inference-only mode after that.

POST /admin/training/state payload

{"state": "<value>"}

Any other value is rejected with 422 Unprocessable Entity.

GET /admin/training/state response

{"state": "Training."}

The state field reflects what the component did with the most recently processed event:

Persistency component configuration

Persistency for detector components is enabled through the persist block in the component configuration file. When present, the component automatically saves its learned state to disk on a configurable schedule.

detectors:
  NewValueDetector:
    method_type: new_value_detector
    persist:
      path: ./state          # Directory to store state files (supports fsspec URLs)
      interval_seconds: 300  # Save every 5 minutes (default)
      events_until_save: 1000  # Also save after every 1000 ingested events (optional)
      auto_load: true        # Restore previous state on startup (default: false)
      storage_options: {}    # Extra options passed to fsspec (e.g. S3 credentials)