Version: 0.16

Tracer

Defines a logging and tracing output method.

This object can be configured from the WebUI under Settings › Telemetry › Tracers

Fields

Tracer is a multi-variant object: each instance has an @type discriminator selecting one of the variants below, and each variant carries its own set of fields.

`@type: "Log"`

Log file

`path`

Type: String · required

The path to the log file

`prefix`

Type: String · default: "stalwart"

The prefix for the log file

`rotate`

Type: LogRotateFrequency · default: "daily"

The frequency to rotate the log file

`ansi`

Type: Boolean · default: true

Whether to use ANSI colors in logs

`multiline`

Type: Boolean · default: false

Whether to write log entries as a single line or multiline

`enable`

Type: Boolean · default: true

Enable or disable the tracer

`level`

Type: TracingLevel · default: "info"

The logging level for this tracer

`lossy`

Type: Boolean · default: false

Whether to drop log entries if there is backlog

`events`

Type: EventType[]

List of events to include or exclude based on filter mode

`eventsPolicy`

Type: EventPolicy · default: "exclude"

How to interpret the events list

`@type: "Stdout"`

Console

`buffered`

Type: Boolean · default: true

Whether to buffer log entries before writing to console

`ansi`

Type: Boolean · default: false

Whether to use ANSI colors in logs

`multiline`

Type: Boolean · default: false

Whether to write log entries as a single line or multiline

`enable`

Type: Boolean · default: true

Enable or disable the tracer

`level`

Type: TracingLevel · default: "info"

The logging level for this tracer

`lossy`

Type: Boolean · default: false

Whether to drop log entries if there is backlog

`events`

Type: EventType[]

List of events to include or exclude based on filter mode

`eventsPolicy`

Type: EventPolicy · default: "exclude"

How to interpret the events list

`@type: "Journal"`

Systemd Journal

`enable`

Type: Boolean · default: true

Enable or disable the tracer

`level`

Type: TracingLevel · default: "info"

The logging level for this tracer

`lossy`

Type: Boolean · default: false

Whether to drop log entries if there is backlog

`events`

Type: EventType[]

List of events to include or exclude based on filter mode

`eventsPolicy`

Type: EventPolicy · default: "exclude"

How to interpret the events list

`@type: "OtelHttp"`

Open Telemetry (HTTP)

`endpoint`

Type: Uri · required

The endpoint for Open Telemetry

`enableLogExporter`

Type: Boolean · default: true

Whether to export logs to OpenTelemetry

`enableSpanExporter`

Type: Boolean · default: true

Whether to export spans to OpenTelemetry

`throttle`

Type: Duration · default: "1s"

The minimum amount of time that must pass between each 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

`enable`

Type: Boolean · default: true

Enable or disable the tracer

`level`

Type: TracingLevel · default: "info"

The logging level for this tracer

`lossy`

Type: Boolean · default: false

Whether to drop log entries if there is backlog

`events`

Type: EventType[]

List of events to include or exclude based on filter mode

`eventsPolicy`

Type: EventPolicy · default: "exclude"

How to interpret the events list

`@type: "OtelGrpc"`

Open Telemetry (gRPC)

`endpoint`

Type: Uri?

The endpoint for Open Telemetry

`enableLogExporter`

Type: Boolean · default: true

Whether to export logs to OpenTelemetry

`enableSpanExporter`

Type: Boolean · default: true

Whether to export spans to OpenTelemetry

`throttle`

Type: Duration · default: "1s"

The minimum amount of time that must pass between each 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

`enable`

Type: Boolean · default: true

Enable or disable the tracer

`level`

Type: TracingLevel · default: "info"

The logging level for this tracer

`lossy`

Type: Boolean · default: false

Whether to drop log entries if there is backlog

`events`

Type: EventType[]

List of events to include or exclude based on filter mode

`eventsPolicy`

Type: EventPolicy · default: "exclude"

How to interpret the events list

JMAP API

The Tracer object is available via the urn:stalwart:jmap capability.

`x:Tracer/get`

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

This method requires the sysTracerGet permission.

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

`x:Tracer/set`

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

Supports create, update, and destroy operations in a single call.

Create

This operation requires the sysTracerCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Tracer/set",
          {
            "create": {
              "new1": {
                "@type": "Log",
                "ansi": true,
                "enable": true,
                "events": [],
                "eventsPolicy": "exclude",
                "level": "info",
                "lossy": false,
                "multiline": false,
                "path": "Example",
                "prefix": "stalwart",
                "rotate": "daily"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysTracerUpdate permission.

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

Destroy

This operation requires the sysTracerDestroy permission.

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

`x:Tracer/query`

This is a standard Foo/query method as defined in RFC 8620, Section 5.5.

This method requires the sysTracerQuery permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Tracer/query",
          {
            "filter": {}
          },
          "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 tracer id1

Create

stalwart-cli create tracer/log \
  --field path=Example \
  --field prefix=stalwart \
  --field rotate=daily \
  --field ansi=true \
  --field multiline=false \
  --field enable=true \
  --field level=info \
  --field lossy=false \
  --field 'events=[]' \
  --field eventsPolicy=exclude

Query

stalwart-cli query tracer

Update

stalwart-cli update tracer id1 --field description='Updated'

Delete

stalwart-cli delete tracer --ids id1

Nested types

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

Enums

LogRotateFrequency

Value	Label
`daily`	Daily
`hourly`	Hourly
`minutely`	Minutely
`never`	Never

TracingLevel

Value	Label
`error`	Error
`warn`	Warning
`info`	Info
`debug`	Debug
`trace`	Trace

EventPolicy

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

Fields​

@type: "Log"​

path​

prefix​

rotate​

ansi​

multiline​

enable​

level​

lossy​

events​

eventsPolicy​

@type: "Stdout"​

buffered​

ansi​

multiline​

enable​

level​

lossy​

events​

eventsPolicy​

@type: "Journal"​

enable​

level​

lossy​

events​

eventsPolicy​

@type: "OtelHttp"​

endpoint​

enableLogExporter​

enableSpanExporter​

throttle​

timeout​

httpAuth​

httpHeaders​

enable​

level​

lossy​

events​

eventsPolicy​

@type: "OtelGrpc"​

endpoint​

enableLogExporter​

enableSpanExporter​

throttle​

timeout​

httpAuth​

httpHeaders​

enable​

level​

lossy​

events​

eventsPolicy​

JMAP API​

x:Tracer/get​

x:Tracer/set​

Create​

Update​

Destroy​

x:Tracer/query​

CLI​

Fetch​

Create​

Query​

Update​

Delete​

Nested types​

HttpAuth​

HttpAuthBasic​

username​

secret​

SecretKey​

SecretKeyValue​

secret​

SecretKeyEnvironmentVariable​

variableName​

SecretKeyFile​

filePath​

HttpAuthBearer​

bearerToken​

Fields

`@type: "Log"`

`path`

`prefix`

`rotate`

`ansi`

`multiline`

`enable`

`level`

`lossy`

`events`

`eventsPolicy`

`@type: "Stdout"`

`buffered`

`ansi`

`multiline`

`enable`

`level`

`lossy`

`events`

`eventsPolicy`

`@type: "Journal"`

`enable`

`level`

`lossy`

`events`

`eventsPolicy`

`@type: "OtelHttp"`

`endpoint`

`enableLogExporter`

`enableSpanExporter`

`throttle`

`timeout`

`httpAuth`

`httpHeaders`

`enable`

`level`

`lossy`

`events`

`eventsPolicy`

`@type: "OtelGrpc"`

`endpoint`

`enableLogExporter`

`enableSpanExporter`

`throttle`

`timeout`

`httpAuth`

`httpHeaders`

`enable`

`level`

`lossy`

`events`

`eventsPolicy`

JMAP API

`x:Tracer/get`

`x:Tracer/set`

Create

Update

Destroy

`x:Tracer/query`

CLI

Fetch

Create

Query

Update

Delete

Nested types

HttpAuth

HttpAuthBasic

`username`

`secret`

SecretKey

SecretKeyValue

`secret`

SecretKeyEnvironmentVariable

`variableName`

SecretKeyFile

`filePath`

HttpAuthBearer

`bearerToken`