aws / aws/amazon-q-developer-cli
Add OpenTelemetry Export for Usage Metrics
- Lingua principale
- Rust
- Stelle
- 2k
- Fork
- 439
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
## 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`
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia leggendo crates/cli/src/cli/chat/token_counter.rs e crates/cli/src/database/settings.rs, quindi esamina l’infrastruttura di telemetria esistente e la documentazione di OpenTelemetry Rust indicata. Definisci la configurazione supportata, l’ambito delle metriche, le garanzie sulla privacy e il comportamento di esportazione prima dell’implementazione; il lavoro è completo quando l’esportazione delle metriche OTLP tramite opt-in funziona senza esporre PII e rimane separata dalla telemetria AWS.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- rust
- Ambito
- cli, observability
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Ferma
- Chiarezza
- Da chiarire
- Idoneità per principianti
- 25/100