Hyperterse — Agentic server framework.

Hyperterse integrates with OpenTelemetry for distributed tracing and metrics. Tracing covers the execution path, database connectors, and MCP traffic. Structured logging provides operational visibility at every level.

Tracing

When tracing is on, Hyperterse records spans for each stage of tool execution:

Span	Attributes
MCP request handling	Method, tool name, request ID
Auth plugin execution	Plugin name, tool name, success/failure
Input transform	Tool name, script path
Connector execution	Adapter name, connector type, cache hit/miss
Output transform	Tool name, script path
Connector initialization	Adapter name, connector type

Traces follow the OpenTelemetry specification and export to any compatible backend: Jaeger, Zipkin, Grafana Tempo, Datadog, AWS X-Ray (via ADOT collector), or any OTLP receiver.

Metrics

Metric	Type	Description
Tool invocation count	Counter	`tools/call` requests per tool
Execution duration	Histogram	End-to-end time per tool
Cache hit/miss ratio	Counter	Hits vs. misses per query
Connector execution time	Histogram	Time in connector `Execute` calls
Auth failure count	Counter	Rejections per plugin

Metrics export through the configured OpenTelemetry meter provider.

Structured logging

Hyperterse uses a tagged structured logger with the following fields:

Timestamp — ISO 8601.
Level — ERROR (1), WARN (2), INFO (3), DEBUG (4).
Tag — component identifier: runtime, executor, connector, mcp, auth.
Message — descriptive text.
Fields — structured key-value pairs (tool name, adapter, duration, error details).

Log levels

Level	Value	Description
Error	1	Unrecoverable failures. Connector init failures, fatal config errors.
Warn	2	Recoverable issues. Cache misses on expected hits, slow queries.
Info	3	Operational events. Startup, shutdown, tool registration, requests.
Debug	4	Diagnostic detail. Substituted statements, auth context, cache keys.

Configure via server.log_level in .hyperterse, or --log-level / --verbose CLI flags.

Log routing

Flag	Description
`--log-file <path>`	Write logs to a file instead of stderr.
`--log-tags <tags>`	Filter output to specific component tags.

Attribute redaction

Sensitive values are redacted before export:

Connection strings — replaced with [REDACTED] in trace spans.
API keys — auth policy values excluded from trace attributes.
Statement parameters — input values in substituted statements logged at debug level only.

Redaction is applied at the observability contract layer, not per-exporter.

Configuration

server:
  log_level: 3
  observability:
    tracing:
      enabled: true
      endpoint: 'http://localhost:4318/v1/traces'
    metrics:
      enabled: true
      endpoint: 'http://localhost:4318/v1/metrics'

When tracing or metrics are not configured, they default to disabled.

Collector integration

Hyperterse exports via OTLP over HTTP. Point the endpoint to your collector:

Backend	Configuration
Jaeger	OTLP receiver on port 4318
Grafana Tempo	OTLP receiver
Datadog Agent	OTLP ingestion endpoint
AWS X-Ray	ADOT collector with OTLP receiver

Quick start with Jaeger

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

Set the tracing endpoint to http://localhost:4318/v1/traces and view traces at http://localhost:16686.

Getting started

Foundation

Agents

Tools

Resources

Prompts

Runtime

Databases

Deployment

Security

Observability

Tracing

Metrics

Structured logging

Log levels

Log routing

Attribute redaction

Configuration

Collector integration

Quick start with Jaeger

​Tracing

​Metrics

​Structured logging

​Log levels

​Log routing

​Attribute redaction

​Configuration

​Collector integration

​Quick start with Jaeger

Tracing

Metrics

Structured logging

Log levels

Log routing

Attribute redaction

Configuration

Collector integration

Quick start with Jaeger