Metrics

Configures metrics collection and export via OpenTelemetry and Prometheus.

This object can be configured from the WebUI under Settings › Telemetry › Metrics › General Settings › Telemetry › Metrics › OpenTelemetry Settings › Telemetry › Metrics › Prometheus

Fields

`openTelemetry`

Type: MetricsOtel · required

OpenTelemetry metrics configuration

`prometheus`

Type: MetricsPrometheus · required

Prometheus metrics endpoint configuration

`metrics`

Type: MetricType[]

List of metrics to include or exclude based on filter mode

`metricsPolicy`

Type: EventPolicy · default: "exclude"

How to interpret the metrics list

JMAP API

The Metrics singleton is available via the urn:stalwart:jmap capability.

`x:Metrics/get`

This is a standard Foo/get method as defined in RFC 8620, Section 5.1.

For singletons, the ids argument should be the literal singleton (or null to return the single instance).

This method requires the sysMetricsGet permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Metrics/get",
          {
            "ids": [
              "singleton"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

`x:Metrics/set`

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

For singletons, only the update argument with id singleton is accepted; create and destroy arguments are rejected.

This method requires the sysMetricsUpdate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Metrics/set",
          {
            "update": {
              "singleton": {
                "openTelemetry": {
                  "@type": "Disabled"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

CLI

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Fetch

stalwart-cli get Metrics

Update

stalwart-cli update Metrics --field openTelemetry='{"@type":"Disabled"}'

Nested types

MetricsOtel

OpenTelemetry metrics configuration.

Disabled: Disabled. No additional fields.
Http: HTTP. Carries the fields of MetricsOtelHttp.
Grpc: gRPC. Carries the fields of MetricsOtelGrpc.

MetricsOtelHttp

OpenTelemetry HTTP metrics exporter.

`endpoint`

Type: Uri · required

The endpoint for Open Telemetry

`interval`

Type: Duration · default: "1m"

The minimum amount of time that must pass between each push request to the OpenTelemetry endpoint

`timeout`

Type: Duration · default: "10s"

Maximum amount of time that Stalwart will wait for a response from the OpenTelemetry endpoint

`httpAuth`

Type: HttpAuth · required

The type of HTTP authentication to use

`httpHeaders`

Type: Map<String, String>

Additional headers to include in HTTP requests

HttpAuth

Defines the HTTP authentication method to use for HTTP requests.

Unauthenticated: Anonymous. No additional fields.
Basic: Basic Authentication. Carries the fields of HttpAuthBasic.
Bearer: Bearer Token. Carries the fields of HttpAuthBearer.

HttpAuthBasic

HTTP Basic authentication credentials.

`username`

Type: String · required

Username for HTTP Basic Authentication

`secret`

Type: SecretKey · required

Password for HTTP Basic Authentication

SecretKey

A secret value provided directly, from an environment variable, or from a file.

Value: Secret value. Carries the fields of SecretKeyValue.
EnvironmentVariable: Secret read from environment variable. Carries the fields of SecretKeyEnvironmentVariable.
File: Secret read from file. Carries the fields of SecretKeyFile.

SecretKeyValue

A secret value provided directly.

`secret`

Type: String · required · secret

Password or secret value

SecretKeyEnvironmentVariable

A secret value read from an environment variable.

`variableName`

Type: String · required

Environment variable name to read the secret from

SecretKeyFile

A secret value read from a file.

`filePath`

Type: String · required

File path to read the secret from

HttpAuthBearer

HTTP Bearer token authentication.

`bearerToken`

Type: SecretKey · required

Bearer token for HTTP Bearer Authentication

MetricsOtelGrpc

OpenTelemetry gRPC metrics exporter.

`endpoint`

Type: Uri?

The endpoint for Open Telemetry

`interval`

Type: Duration · default: "1m"

The minimum amount of time that must pass between each push request to the OpenTelemetry endpoint

`timeout`

Type: Duration · default: "10s"

Maximum amount of time that Stalwart will wait for a response from the OpenTelemetry endpoint

MetricsPrometheus

Prometheus metrics endpoint configuration.

Disabled: Disabled. No additional fields.
Enabled: Enabled. Carries the fields of MetricsPrometheusProperties.

MetricsPrometheusProperties

Prometheus metrics endpoint authentication.

`authSecret`

Type: SecretKeyOptional · required

The Prometheus endpoint’s secret for Basic authentication

`authUsername`

Type: String?

The Prometheus endpoint’s username for Basic authentication

SecretKeyOptional

An optional secret value, or none.

None: No secret. No additional fields.
Value: Secret value. Carries the fields of SecretKeyValue.
EnvironmentVariable: Secret read from environment variable. Carries the fields of SecretKeyEnvironmentVariable.
File: Secret read from file. Carries the fields of SecretKeyFile.

Enums

EventPolicy

Value	Label
`include`	Only include the specified events
`exclude`	Exclude the specified events