> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> OpenTelemetry tracing and metrics, structured logging, attribute redaction, and collector integration.

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

```yaml theme={null}
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

```bash theme={null}
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`.