hermes-otel-plugin

English | 中文

hermes-otel-plugin collects Hermes request, model, skill, and tool observability data from native Hermes hooks and exports traces and metrics over OTLP HTTP/protobuf.

Features

• Exports the main request trace: hermes_request -> user_message -> main -> provider:model -> skill:* -> skill_call:* -> tool:* -> assistant_message
• Exports request, model, tool, token, and skill metrics
• Uses semantic attribute names such as session_id, model_name, model_api_mode, tool_name, skill_name, and input_preview
• New telemetry no longer emits raw openclaw.* or hermes.* attribute prefixes

Installation

hermes plugins install GuanceCloud/hermes-otel-plugin

The installer copies config.yaml.example to config.yaml. Restart Hermes after updating the configuration:

hermes gateway restart

Configuration

Example:

enabled: true
endpoint: http://127.0.0.1:4318
trace_path: v1/traces
metric_path: v1/metrics
agent_provider: hermes
service_name: hermes-otel-plugin
flush_interval_ms: 15000
root_span_ttl_ms: 600000
headers: {}
global_tags:
  team: apm
resource_attributes:
  service.namespace: hermes

Core fields:

• endpoint: OTLP HTTP base URL
• trace_path: trace export path, default v1/traces
• metric_path: metric export path, default v1/metrics
• agent_provider: resource-level agent_provider
• service_name: OTEL service.name
• headers: OTLP request headers
• global_tags: global fixed tags
• resource_attributes: OTEL resource attributes
• sample_rate: trace sampling rate in the range 0~1
• flush_interval_ms: metric export interval
• root_span_ttl_ms: fallback TTL for unfinished turns

Header configuration options:

• config.yaml: configure headers as a YAML object
• HERMES_OTEL_HEADERS: override headers from environment using either JSON or comma-separated pairs such as Authorization=Bearer xxx,X-Tenant=tenant-a
• Numeric overrides such as HERMES_OTEL_SAMPLE_RATE=0.5, HERMES_OTEL_FLUSH_INTERVAL_MS=20000, and HERMES_OTEL_ROOT_SPAN_TTL_MS=600000 are also supported

Example:

headers:
  Authorization: Bearer your-token
  X-Tenant: tenant-a

Example:

export HERMES_OTEL_HEADERS='{"Authorization":"Bearer your-token","X-Tenant":"tenant-a"}'
export HERMES_OTEL_SAMPLE_RATE=0.5
export HERMES_OTEL_FLUSH_INTERVAL_MS=20000

Metrics

• hermes.requests
• hermes.request.duration
• hermes.model.calls
• hermes.model.duration
• hermes.tokens
• hermes.tool.calls
• hermes.tool.errors
• hermes.tool.duration
• hermes.skill.activations

Trace Attributes

Representative exported attributes:

• Session and entry: session_id, session_key, entry_point, final_status
• Model and API: model_provider, model_name, model_api_mode, model_api_base_url, model_api_call_index
• Skill and tool: skill_name, skill_kind, skill_source, skill_call_id, tool_name, tool_call_id, tool_target, tool_command, tool_outcome
• Content previews: input_preview, output_preview
• Aggregated request summary: skills, skill_count, tools, tool_count, tool_targets, tool_commands, tool_result_statuses

Validation

Local validation used during development:

python3 -m unittest discover -s tests

The plugin was also verified against an OTLP HTTP receiver and a local DataKit endpoint.

Known Limitations

• Hermes does not expose the OpenClaw diagnostics event bus, so queue depth, stuck session, and queued/processed message metrics cannot be migrated 1:1
• Skill detection is inferred from tool arguments, result payloads, and command paths, so custom workflows may require extra rules