# Tools Telemetry Exporter Plugin

> Author: Bar Haim
> Version: 0.1.0

Export comprehensive tool invocation telemetry to OpenTelemetry for observability and monitoring.

## Hooks
- `tool_pre_invoke`
- `tool_post_invoke`

## Config
```yaml
config:
  export_full_payload: false
  max_payload_bytes_size: 10000  # 10 KB default
```

## Features

- **Pre-Invocation Telemetry**: Captures request context, tool metadata, target MCP server details, and tool arguments
- **Post-Invocation Telemetry**: Captures request context, optional tool results, and error status
- **Automatic Payload Truncation**: Large results are truncated to respect size limits
- **Graceful Degradation**: Automatically disables if OpenTelemetry is not available
- **Sensitive Header Redaction**: Auth-bearing headers are masked before export

## Exported Attributes

### Pre-Invocation (`tool.pre_invoke`)
- Request metadata: `request_id`, `user`, `tenant_id`, `server_id`
- Target server: `target_mcp_server.id`, `target_mcp_server.name`, `target_mcp_server.url`
- Tool info: `tool.name`, `tool.target_tool_name`, `tool.description`
- Invocation data: `tool.invocation.args`, `headers` (sensitive values redacted)

### Post-Invocation (`tool.post_invoke`)
- Request metadata: `request_id`, `user`, `tenant_id`, `server_id`
- Results: `tool.invocation.result` (if `export_full_payload` is enabled and no error)
- Status: `tool.invocation.has_error`

## Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `export_full_payload` | `false` | Export full tool results in post-invocation telemetry |
| `max_payload_bytes_size` | `10000` | Maximum payload size in bytes before truncation |

## Requirements

OpenTelemetry enabled on ContextForge (see [Observability Setup](../../docs/docs/manage/observability.md#opentelemetry-external)).


## Usage

```yaml
plugins:
  - name: "ToolsTelemetryExporter"
    kind: "plugins.tools_telemetry_exporter.telemetry_exporter.ToolsTelemetryExporterPlugin"
    hooks: ["tool_pre_invoke", "tool_post_invoke"]
    mode: "permissive"
    priority: 200  # Run late to capture all context
    config:
        export_full_payload: false
        max_payload_bytes_size: 10000
```

## Limitations

- Requires active OpenTelemetry tracing to export telemetry
- No local buffering; telemetry exported in real-time only

## Security Notes

- Tool arguments are always exported in pre-invocation telemetry
- Sensitive headers are redacted before export, including `Authorization`, `Cookie`, `X-API-Key`, `Proxy-Authorization`, and vault/delegation token headers
- Consider running PII filter plugin before this plugin to sanitize tool arguments before export
- Leave `export_full_payload` disabled unless you explicitly need result content in telemetry
