aws / aws/amazon-q-developer-cli

Add OpenTelemetry Export for Usage Metrics

Aperta
#2,108 3 commenti 5 reazioni 0 assegnatari Vedi su GitHub
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.