aws / aws/amazon-q-developer-cli
Add OpenTelemetry Export for Usage Metrics
- Dominant language
- Rust
- Stars
- 2k
- Forks
- 439
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Add OpenTelemetry (OTLP) export capability to allow users to send usage metrics to their own observability platforms. This would complement the existing AWS telemetry by providing users with their own usage data.
## Motivation
Users currently have no way to track their token usage, API calls, or tool usage patterns. Adding OTLP export would allow integration with existing observability stacks (Prometheus, Grafana, DataDog, etc.) without requiring Amazon Q to build custom dashboards.
## Proposed Implementation
### Configuration
Support configuration via environment variables (following OTel conventions):
```bash
# Enable OTLP export
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc" # or "http/protobuf"
export OTEL_SERVICE_NAME="amazon-q-cli"
export OTEL_METRICS_EXPORTER="otlp"
# Optional: Headers for authentication
export OTEL_EXPORTER_OTLP_HEADERS="api-key=your-key"
# Control which metrics to export
export Q_OTEL_METRICS_ENABLED="true"
export Q_OTEL_METRICS_INCLUDE="tokens,api_calls,tools" # opt-in specific metrics
```
### Metrics to Export
```rust
// Token usage (from existing token_counter.rs)
amazonq.tokens.total{direction="input", tool="bash"}
amazonq.tokens.total{direction="output", tool="edit"}
// API calls
amazonq.api.requests.total{operation="send_message", status="success"}
amazonq.api.duration.ms{operation="send_message"}
// Tool usage
amazonq.tools.invocations.total{tool="read", accepted="true", success="true"}
amazonq.tools.duration.ms{tool="bash"}
// Conversations
amazonq.conversations.messages.total{type="user"}
amazonq.conversations.duration.seconds
```
### Implementation Notes
- Reuse existing telemetry infrastructure where possible
- Leverage token counting from `crates/cli/src/cli/chat/token_counter.rs`
- Add opentelemetry and opentelemetry-otlp crates
- Separate from AWS telemetry - only export user-relevant metrics
- No PII in metrics (no message content, file paths, etc.)
### Example Usage
```bash
# Start local Prometheus + Grafana stack
docker-compose up -d
# Configure Q to export metrics
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export Q_OTEL_METRICS_ENABLED="true"
# Use Q normally - metrics automatically exported
q chat
# View metrics in Grafana dashboard
```
## Benefits
- Zero additional UI/commands needed
- Works with any OTel-compatible backend
- Users control their own data
- Follows industry standards
- Minimal implementation effort
## Privacy & Performance
- Opt-in only (requires explicit OTEL_EXPORTER_OTLP_ENDPOINT)
- Async export (non-blocking)
- Batched exports to minimize overhead
- No metrics exported by default
- Completely separate from AWS telemetry
## Alternative Approach
Could also support file-based config in existing settings.json:
```json
{
"otel": {
"endpoint": "http://localhost:4317",
"protocol": "grpc",
"metrics": {
"enabled": true,
"include": ["tokens", "api_calls", "tools"]
}
}
}
```
## References
- OpenTelemetry Rust: https://github.com/open-telemetry/opentelemetry-rust
- OTel Environment Variables: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
- Existing settings: `crates/cli/src/database/settings.rs`
Contributor guide
Assessment
This issue has not been assessed yet.