haraka-plugin-opentelemetry

OpenTelemetry tracing and metrics plugin for the Haraka SMTP server.

Instruments the full SMTP lifecycle, from TCP connection through queue delivery, and exports spans and metrics to any OTLP-compatible backend.

Features

• One span per SMTP connection with per-message events (HELO/EHLO, MAIL FROM, RCPT TO, DATA, QUEUE)
• Span attributes for client/server address, port, and message size
• Six out-of-the-box metrics covering connections, hook invocations, connection duration, message size, delivery results, and liveness
• Traces and metrics can each be disabled independently via config
• Zero code changes required: endpoint and auth are wired via standard OTEL environment variables
• Compatible with Jaeger, Grafana Tempo, HyperDX, Honeycomb, Datadog, and any other OTLP HTTP backend

Requirements

• Node.js >= 22
• Haraka SMTP server

Install

Navigate to your Haraka installation directory:

cd /path/to/local/haraka

Install the plugin:

npm install haraka-plugin-opentelemetry

Register the plugin:

echo "opentelemetry" >> config/plugins

Restart Haraka:

service haraka restart

Configuration

Copy the default config into your Haraka config directory:

cp node_modules/haraka-plugin-opentelemetry/config/opentelemetry.ini config/opentelemetry.ini

opentelemetry.ini

[main]
; Set to false to disable the plugin entirely
enabled = true

; OTel resource attributes identifying this service
service_name = haraka
service_version = 1.0.0

; Extra resource attributes as comma-separated key=value pairs
; resource_attributes = env=production,region=us-east-1

[traces]
; Set to false to disable trace export without removing the plugin
enabled = true

[metrics]
; Set to false to disable metric export without removing the plugin
enabled = true

; How often metrics are pushed, in milliseconds
export_interval_ms = 60000

Environment variables

Endpoint, authentication, and other export settings follow the standard OTLP exporter spec. These take precedence over opentelemetry.ini resource attributes.

Variable	Default	Description
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	Base endpoint for all signals
OTEL_EXPORTER_OTLP_HEADERS		Auth/routing headers for all signals (key=val,key2=val2)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT		Trace-specific endpoint override
OTEL_EXPORTER_OTLP_TRACES_HEADERS		Trace-specific headers override
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT		Metrics-specific endpoint override
OTEL_EXPORTER_OTLP_METRICS_HEADERS		Metrics-specific headers override
OTEL_SERVICE_NAME		Overrides service.name resource attribute
OTEL_RESOURCE_ATTRIBUTES		Additional resource attributes (k=v,k2=v2)

Traces

Each inbound SMTP connection produces one smtp.connection span (kind: SERVER) that covers the full connection lifetime. SMTP protocol events are recorded as span events on that root span.

Root span attributes

Attribute	Description
client.address	Remote client IP
client.port	Remote client port
net.peer.name	Remote hostname
server.address	Local server IP
server.port	Local server port
smtp.message.size_bytes	Message body size in bytes (set after DATA)

Span events

Event	Attributes
smtp.helo / smtp.ehlo	smtp.helo_host
smtp.mail	smtp.mail_from
smtp.rcpt	smtp.rcpt_to
smtp.data
smtp.queue / smtp.queue_ok	smtp.queue_msg
smtp.reset_transaction

Metrics

Metric	Type	Unit	Description
haraka.connections	Counter		Total inbound SMTP connections
haraka.hook.total	Counter		Hook invocations; labeled by haraka.hook
haraka.connection.duration	Histogram	ms	SMTP connection duration
haraka.message.size	Histogram	bytes	Message body size
haraka.messages	Counter		Messages by delivery result; labeled by smtp.result (queued, delivered, deferred, bounced)
haraka.up	Observable Gauge		Always 1 while the plugin is loaded

Changelog

See CHANGELOG.md.

Contributing

Pull requests are welcome. Please open an issue first to discuss significant changes.

Run tests:

npm test

Check code style:

npm run lint

Auto-fix style:

npm run format

License

MIT. See LICENSE.