execreceiver

Exec Receiver

Status
Stability	alpha: logs
Distributions
Issues

An OpenTelemetry Collector receiver that runs external commands and captures their stdout/stderr output as log records.

Security Considerations

This receiver executes arbitrary commands with the same privileges as the collector process. Keep the following in mind:

• Restrict access to the collector configuration. Anyone who can modify the config can execute commands on the host.
• Environment is clean by default. Commands start with an empty environment unless inherit_environment: true is set. Avoid inheriting the collector's environment when it may contain secrets (API keys, tokens, credentials).
• Be mindful of command output. Output flows into the telemetry pipeline and may contain sensitive data (PII, credentials, internal paths). Use processors to filter or redact as needed.
• Avoid passing secrets as command arguments. The full command string is recorded in the exec.command log attribute on every record.
• Set exec_timeout in scheduled mode to prevent runaway processes from accumulating.

Modes

Scheduled (default)

Runs the command on a configurable interval. Each execution produces a batch of log records from the command's output. If the command is still running when the next interval fires and the max_concurrent limit has been reached, that tick is skipped and a warning is logged.

Streaming

Runs the command continuously and reads output line-by-line as it is produced. If the command exits, it is restarted after a configurable delay with exponential backoff. The backoff starts at restart_delay, doubles on each consecutive failure, and caps at max_restart_delay. It resets when the command runs successfully for longer than restart_delay.

Configuration

Example: Scheduled

receivers:
  exec:
    command: ["df", "-h"]
    mode: scheduled
    interval: 30s

Example: Streaming

receivers:
  exec:
    command: ["tail", "-f", "/var/log/syslog"]
    mode: streaming
    restart_delay: 5s
    include_stderr: false

Example: Multiple Receivers

receivers:
  exec/disk:
    command: ["df", "-h"]
    mode: scheduled
    interval: 60s
  exec/uptime:
    command: ["uptime"]
    mode: scheduled
    interval: 300s
  exec/journal:
    command: ["journalctl", "-f", "-o", "json"]
    mode: streaming

service:
  pipelines:
    logs:
      receivers: [exec/disk, exec/uptime, exec/journal]
      processors: [batch]
      exporters: [debug]

See the examples/ directory for complete collector configurations.

Log Record Schema

Each line of output produces a log record with the following structure:

Attributes

Resource Attributes

Self-Observability

The receiver exposes internal metrics for monitoring its own operation:

Standard receiver metrics (otelcol_receiver_accepted_log_records, otelcol_receiver_refused_log_records) are also available via the built-in ObsReport instrumentation.

Process Management

• Graceful shutdown: On shutdown, the receiver sends SIGINT to running processes, then SIGKILL after 5 seconds if the process hasn't exited.
• Scheduled mode: Each execution runs independently. If exec_timeout is set, the process is killed if it exceeds the timeout.
• Streaming mode: The command runs continuously. If it exits, the receiver waits before restarting with exponential backoff (starting at restart_delay, doubling on each consecutive failure, capped at max_restart_delay). The backoff resets when the command runs longer than restart_delay. The restart counter metric tracks how many times a streaming command has been restarted.
• Environment: By default, commands start with a clean environment. Use environment to set variables, or inherit_environment: true to inherit the collector's environment as a base.

Audit Logging

The receiver emits structured INFO-level log messages for each command execution to provide an audit trail. These logs are written to the collector's own log output (not the telemetry pipeline) and include the following fields:

In scheduled mode, a "Command exited" message is logged after each execution completes.

In streaming mode, a "Command started" message is logged when the process starts (with command, pid, mode, and receiver_id fields), and a "Command exited" message is logged when the process exits (with all fields including exit_code and duration).

Building a Custom Collector

Use the OpenTelemetry Collector Builder (ocb) to include this receiver in a custom collector distribution:

# builder-config.yaml
dist:
  name: custom-otelcol
  output_path: ./dist

receivers:
  - gomod: github.com/graphaelli/execreceiver v0.1.0

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.147.0

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.147.0

Then build:

ocb --config builder-config.yaml

Benchmarks

Run benchmarks with:

go test -bench=. -benchtime=3s ./...

Example results (Apple M4 Pro):

BenchmarkLogRecordCreation/1-lines      994836     1188 ns/op     848 B/op    21 allocs/op
BenchmarkLogRecordCreation/10-lines     519051     2372 ns/op    4768 B/op    97 allocs/op
BenchmarkLogRecordCreation/100-lines     88672    13651 ns/op   43408 B/op   820 allocs/op
BenchmarkLogRecordCreation/1000-lines     8958   136036 ns/op  425973 B/op  8023 allocs/op
BenchmarkScheduledExecution/1-lines       331  3718713 ns/op
BenchmarkScheduledExecution/1000-lines    334  3587836 ns/op
BenchmarkReceiverLifecycle              38466    27741 ns/op    8470 B/op   112 allocs/op