Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/actions/spelling/allow.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,14 @@ fcf
frop
fuzzer
github
Grafana
hardenings
https
iostream
iostreams
istream
istreams
Jaeger
jvm
JVM
JVMs
Expand All @@ -27,6 +29,7 @@ learntype
lfill
libcap
libpcre
libprotobuf
libstemmer
libtextcat
lri
Expand All @@ -36,20 +39,25 @@ mmaped
mtls
ond
onlinedocs
opentelemetry
ostream
ostreams
otel
otlp
plugin
plugins
postgre
Postgre
postgres
protobuf
retpoline
retuns
rfill
sls
sni
spnego
ssh
traceparent
ubsan
ubuntu
Uppercases
Expand Down
220 changes: 219 additions & 1 deletion data/settings.js
Original file line number Diff line number Diff line change
Expand Up @@ -6371,7 +6371,7 @@ Creates a new event exporter. The filter name refers to the
event_exporter_driver: {
tags: [ 'event-export' ],
values: setting_types.ENUM,
values_enum: [ 'log', 'file', 'unix', 'http-post', 'drop' ],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  - metric_export_sample_by_permille UINT → _percent STR (0.001..100, DENOM 100000); hash % 1000
    < permille text and examples.
  - event_exporter_opentelemetry_trace_id_field no longer exists; trace_id is random per session
    and propagated, not SHA-1(session); span_id not SHA-1 derived; no Span.Link for <base>:<rest>
    sessions.
  - service.instance.id is UUIDv4 per stats process, not hostname; request timeout default 2s not
    10s; log records also protobuf now.
  - Missing: propagation docs (IMAP ID x-trace-id/x-parent-id, XCLIENT X-TRACE-ID/X-PARENT-ID,
    HTTP headers, auth protocol trace_id/parent_span_id, userdb lookup fields), _-prefixed
    reserved field convention, span-marking rules.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 All covered in the current text: metric_export_sample_by_percent, random trace and span ids (no trace_id_field, no Span.Link), service.instance.id as a UUID, the 2s request timeout, protobuf log records, the propagation section (IMAP ID x-trace-id / x-parent-span-id, XCLIENT TRACE-ID / PARENT-SPAN-ID, traceparent, auth and userdb fields), reserved _ fields and span owners.

values_enum: [ 'log', 'file', 'unix', 'http-post', 'drop', 'opentelemetry' ],
default: 'log',
seealso: [ '[[link,event_export_drivers]]' ],
text: `
Expand Down Expand Up @@ -6445,6 +6445,122 @@ Timeout when connecting to unix socket with
Path to event unix socket with [[setting,event_exporter_driver,unix]].`
},

event_exporter_opentelemetry_url: {
added: {
settings_event_exporter_opentelemetry_added: false,
},
tags: [ 'event-export' ],
values: setting_types.STRING,
default: 'http://localhost:4318',
seealso: [ '[[link,event_export_opentelemetry]]',
'event_exporter_opentelemetry_emit_logs' ],
text: `
Base URL of the OTLP/HTTP collector when using
[[setting,event_exporter_driver,opentelemetry]]. The exporter POSTs
spans to \`<url>/v1/traces\` and (when
[[setting,event_exporter_opentelemetry_emit_logs]] is enabled) log
records to \`<url>/v1/logs\`. The wire format and
\`Content-Type\` are selected by [[setting,event_exporter_format]]:

* \`protobuf\` → \`application/x-protobuf\` (OTLP/HTTP+protobuf binary)
* \`json\` → \`application/json\` (OTLP/HTTP+JSON, proto3 ProtoJSON
canonical encoding)

Spans and log records use the same format and are sent in batches, see
[[setting,event_exporter_opentelemetry_flush_interval]].

Only OTLP/HTTP is implemented. OTLP/gRPC is not supported; point this
setting at a collector that accepts OTLP/HTTP (the OpenTelemetry
Collector, Jaeger v2, Grafana Tempo, etc.).`
},

event_exporter_opentelemetry_emit_spans: {
added: {
settings_event_exporter_opentelemetry_added: false,
},
tags: [ 'event-export' ],
values: setting_types.BOOLEAN,
default: 'yes',
seealso: [ '[[link,event_export_opentelemetry]]',
'event_exporter_opentelemetry_emit_logs' ],
text: `
When enabled (the default), the exporter emits OTLP Spans to
\`<url>/v1/traces\`. Disable only when you want the exporter to
ship log records exclusively (set together with
[[setting,event_exporter_opentelemetry_emit_logs,yes]]).`
},

event_exporter_opentelemetry_emit_logs: {
added: {
settings_event_exporter_opentelemetry_added: false,
},
tags: [ 'event-export' ],
values: setting_types.BOOLEAN,
default: 'no',
seealso: [ '[[link,event_export_opentelemetry_logs]]',
'event_exporter_opentelemetry_emit_spans' ],
text: `
When enabled, the exporter emits an OTLP LogRecord to
\`<url>/v1/logs\` for every matched event that carries a
formatted log message (\`e_info()\`, \`e_warning()\`, \`e_error()\`,
\`e_debug()\` call sites). The LogRecord shares its \`trace_id\` with the
trace of the span it belongs to, and its \`span_id\` with that span, so
collectors link logs and traces.

Log records use the wire format selected by
[[setting,event_exporter_format]], like spans. Severity is mapped to the OTel
severity model (DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21;
PANIC is sent as FATAL4=24).

Enabling this setting opts the stats process into receiving the
formatted message text from each dovecot service; the wire cost is
zero when the corresponding metric's filter does not match an event.`
},

event_exporter_opentelemetry_flush_interval: {
added: {
settings_event_exporter_opentelemetry_added: false,
},
tags: [ 'event-export' ],
values: setting_types.TIME_MSECS,
default: '5 secs',
seealso: [ 'event_exporter_opentelemetry_flush_count' ],
text: `
Spans and log records are sent at the latest this long after the first one
was queued, even when [[setting,event_exporter_opentelemetry_flush_count]] has
not been reached. Must not be \`0\`.`
},

event_exporter_opentelemetry_flush_count: {
added: {
settings_event_exporter_opentelemetry_added: false,
},
tags: [ 'event-export' ],
values: setting_types.UINT,
default: 512,
seealso: [ 'event_exporter_opentelemetry_flush_interval',
'event_exporter_opentelemetry_max_pending_requests' ],
text: `
Spans and log records are sent as soon as this many are queued, without
waiting for [[setting,event_exporter_opentelemetry_flush_interval]]. Spans and
log records are queued separately. Must not be \`0\`.`
},

event_exporter_opentelemetry_max_pending_requests: {
added: {
settings_event_exporter_opentelemetry_added: false,
},
tags: [ 'event-export' ],
values: setting_types.UINT,
default: 4,
seealso: [ 'event_exporter_opentelemetry_flush_count' ],
text: `
Maximum number of export requests that can be waiting for the collector's
response. Spans and log records share this limit. While this many requests
are pending, a further batch is dropped and an error is logged with the
number of dropped records. Must not be \`0\`.`
},

execute: {
tags: [ 'execute' ],
values: setting_types.NAMED_LIST_FILTER,
Expand Down Expand Up @@ -7039,6 +7155,24 @@ connection before trying the next IP in parallel. \`0\` = wait until current
connection attempt finishes.`
},

http_client_trace_context: {
tags: [ 'http', 'http_client' ],
values: setting_types.BOOLEAN,
default: 'no',
added: {
trace_context_added: false,
},
seealso: [ '[[link,event_export_opentelemetry]]' ],
text: `
Send a W3C \`traceparent\` header with each request, carrying the trace id
and span id of the event the request was made under. A request that sets its
own \`traceparent\` header keeps it. Requests made under an event without a
trace id or a span id carry no header.

The header lets the receiving service continue the same trace. It also
reveals the trace id to the server, so enable it only for servers you trust.`
},

http_client_user_agent: {
advanced: true,
tags: [ 'http', 'http_client' ],
Expand Down Expand Up @@ -7165,6 +7299,23 @@ The kernel send buffer size for the connection sockets. \`0\` = kernel
defaults.`
},

http_server_trace_context_trusted_networks: {
tags: [ 'http', 'http-server' ],
values: setting_types.BOOLLIST,
added: {
trace_context_added: false,
},
seealso: [ '[[link,event_export_opentelemetry]]' ],
text: `
List of IP addresses or network ranges in CIDR notation (e.g. \`192.168.0.0/24\`
or \`2001:db8::/32\`) whose W3C \`traceparent\` request header is accepted.
The request then continues the trace of the header, so the spans of the
request share the trace id of the caller. Requests from other addresses have
the header ignored. By default no network is trusted.

An invalid network is rejected when the configuration is loaded.`
},

http_server_rawlog_dir: {
changed: {
settings_path_types_added: `Setting type changed. A leading \`~/\` in the value is now expanded to the user's home directory.`,
Expand Down Expand Up @@ -10476,6 +10627,73 @@ Human-readable description of the metric. This is included in the HELP text
sent to OpenMetrics.`
},

metric_export_sample_by: {
added: {
settings_metric_export_sample_by_added: false,
},
tags: [ 'metrics' ],
values: setting_types.NAMED_LIST_FILTER,
seealso: [ '[[link,stats_sample_by]]',
'metric_export_sample_by_field',
'metric_export_sample_by_percent' ],
text: `
Defines a [[link,stats_sample_by,sampling rule]] that decides whether an
event matching this metric is forwarded to the
[[setting,metric_exporter]]. The filter name is an arbitrary identifier
for the rule; the actual sampled field is the
[[setting,metric_export_sample_by_field]] setting inside the block.

Multiple [[setting,metric_export_sample_by]] blocks combine with AND
semantics: an event is exported only if every rule passes. Sampling is
deterministic: events that share the same field value are always sampled
in or out together. Statistics counters are unaffected; sampling applies
only to exported events.`
},

metric_export_sample_by_field: {
added: {
settings_metric_export_sample_by_added: false,
},
tags: [ 'metrics' ],
values: setting_types.STRING,
seealso: [ '[[link,stats_sample_by]]',
'metric_export_sample_by',
'metric_export_sample_by_percent' ],
text: `
Name of the event field whose value is hashed to make the sampling
decision. A common choice is \`session\`, which causes every event in
the same session to be sampled in or out together.

The value \`trace_id\` always uses the trace id of the event; an event field named
\`trace_id\` is not looked up. Sampling by \`trace_id\` keeps every event of a
trace together, including events of other systems sharing the trace id (a
\`traceparent\` header from a trusted network, or IMAP \`ID\` / \`XCLIENT\` from a
trusted proxy). It also keeps a \`doveadm\` command whole: the command's own
events have no \`session\` field, so sampling by \`session\` drops them.

An event without the field, or for \`trace_id\` without a trace id, is dropped
from the export.`
},

metric_export_sample_by_percent: {
added: {
settings_metric_export_sample_by_added: false,
},
tags: [ 'metrics' ],
values: setting_types.STRING,
default: '100',
seealso: [ '[[link,stats_sample_by]]',
'metric_export_sample_by',
'metric_export_sample_by_field' ],
text: `
Percentage of distinct field values that are exported. The valid range is
\`0.001\`..\`100\`; \`0\` is rejected. The default \`100\` exports every event,
which makes the [[setting,metric_export_sample_by]] block a no-op.

For example, \`percent = 10\` exports approximately 10% of distinct field
values, and \`percent = 0.5\` exports approximately 0.5%.`
},

oauth2: {
tags: [ 'oauth2' ],
values: setting_types.NAMED_FILTER,
Expand Down
3 changes: 3 additions & 0 deletions data/updates.js
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ export const updates = {
setting_sqlite_synchronous_added: '2.4.3',
setting_sqlite_busy_timeout_added: '2.4.5',
ssl_sni_settings_reload_added: '2.4.0',
trace_context_added: '2.4.6',
weak_password_schemes: '2.4.0',
variables_auth_variables_protocol: '2.4.0',
variables_login_variables_protocol: '2.4.0',
Expand Down Expand Up @@ -200,6 +201,7 @@ export const updates = {
settings_dovecot_config_version_added: '2.4.0',
settings_dovecot_storage_version_added: '2.4.0',
settings_dovecot_storage_version_thread_index_changed: '2.4.5',
settings_event_exporter_opentelemetry_added: '2.4.6',
settings_imapc_features_auto_capabilities: '2.4.3',
settings_fifo_listener_type_added: '2.4.0',
settings_fts_decoder_tika_url_changed: '2.4.0',
Expand Down Expand Up @@ -232,6 +234,7 @@ export const updates = {
settings_mailbox_defaults_english_changed: '2.4.3',
settings_mailbox_directory_name_legacy_deprecated: '2.4.2',
settings_mailbox_special_use_changed: '2.4.0',
settings_metric_export_sample_by_added: '2.4.6',
settings_metric_fields_changed: '2.4.0',
settings_passdb_default_password_scheme_changed: '2.4.3',
settings_passdb_mechanisms_filter_added: '2.4.0',
Expand Down
Loading
Loading