Set up comprehensive observability for Deepgram integrations with metrics, traces, and alerts. Use when implementing monitoring for Deepgram operations, setting up dashboards, or configuring alerting for Deepgram integration health. Trigger with phrases like "deepgram monitoring", "deepgram metrics", "deepgram observability", "monitor deepgram", "deepgram alerts", "deepgram tracing".
Implement comprehensive observability for Deepgram integrations including metrics, distributed tracing, logging, and alerting.
| Pillar | Tool | Purpose |
|---|---|---|
| Metrics | Prometheus | Performance & usage tracking |
| Traces | OpenTelemetry | Request flow visibility |
| Logs | Structured JSON | Debugging & audit |
| Alerts | AlertManager | Incident notification |
Implement Prometheus counters, histograms, and gauges for key operations.
Integrate OpenTelemetry for end-to-end request tracing.
Set up JSON logging with consistent field names.
Define alerting rules for error rates and latency.
// lib/metrics.ts
import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from 'prom-client';
export const registry = new Registry();
collectDefaultMetrics({ register: registry });
// Request counters
export const transcriptionRequests = new Counter({
name: 'deepgram_transcription_requests_total',
help: 'Total number of transcription requests',
labelNames: ['status', 'model', 'type'],
registers: [registry],
});
// Latency histogram
export const transcriptionLatency = new Histogram({
name: 'deepgram_transcription_latency_seconds',
help: 'Transcription request latency in seconds',
labelNames: ['model', 'type'],
buckets: [0.1, 0.5, 1, 2, 5, 10, 30, 60, 120],
registers: [registry],
});
// Audio duration processed
export const audioProcessed = new Counter({
name: 'deepgram_audio_processed_seconds_total',
help: 'Total audio duration processed in seconds',
labelNames: ['model'],
registers: [registry],
});
// Active connections gauge
export const activeConnections = new Gauge({
name: 'deepgram_active_connections',
help: 'Number of active Deepgram connections',
labelNames: ['type'],
registers: [registry],
});
// Rate limit hits
export const rateLimitHits = new Counter({
name: 'deepgram_rate_limit_hits_total',
help: 'Number of rate limit responses',
registers: [registry],
});
// Cost tracking
export const estimatedCost = new Counter({
name: 'deepgram_estimated_cost_dollars',
help: 'Estimated cost in dollars',
labelNames: ['model'],
registers: [registry],
});
// Metrics endpoint
export async function getMetrics(): Promise<string> {
return registry.metrics();
}
// lib/instrumented-client.ts
import { createClient, DeepgramClient } from '@deepgram/sdk';
import {
transcriptionRequests,
transcriptionLatency,
audioProcessed,
estimatedCost,
} from './metrics';
import { trace, context, SpanStatusCode } from '@opentelemetry/api';
import { logger } from './logger';
const tracer = trace.getTracer('deepgram-client');
const modelCosts: Record<string, number> = {
'nova-2': 0.0043,
'nova': 0.0043,
'base': 0.0048,
};
export class InstrumentedDeepgramClient {
private client: DeepgramClient;
constructor(apiKey: string) {
this.client = createClient(apiKey);
}
async transcribeUrl(url: string, options: { model?: string } = {}) {
const model = options.model || 'nova-2';
const startTime = Date.now();
return tracer.startActiveSpan('deepgram.transcribe', async (span) => {
span.setAttribute('deepgram.model', model);
span.setAttribute('deepgram.audio_url', url);
try {
const { result, error } = await this.client.listen.prerecorded.transcribeUrl(
{ url },
{ model, smart_format: true }
);
const duration = (Date.now() - startTime) / 1000;
if (error) {
transcriptionRequests.labels('error', model, 'prerecorded').inc();
span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
logger.error('Transcription failed', {
model,
error: error.message,
duration,
});
throw error;
}
// Record metrics
transcriptionRequests.labels('success', model, 'prerecorded').inc();
transcriptionLatency.labels(model, 'prerecorded').observe(duration);
const audioDuration = result.metadata.duration;
audioProcessed.labels(model).inc(audioDuration);
const cost = (audioDuration / 60) * (modelCosts[model] || 0.0043);
estimatedCost.labels(model).inc(cost);
span.setAttribute('deepgram.request_id', result.metadata.request_id);
span.setAttribute('deepgram.audio_duration', audioDuration);
span.setAttribute('deepgram.processing_time', duration);
span.setStatus({ code: SpanStatusCode.OK });
logger.info('Transcription completed', {
requestId: result.metadata.request_id,
model,
audioDuration,
processingTime: duration,
cost,
});
return result;
} catch (err) {
const duration = (Date.now() - startTime) / 1000;
transcriptionRequests.labels('exception', model, 'prerecorded').inc();
transcriptionLatency.labels(model, 'prerecorded').observe(duration);
span.setStatus({
code: SpanStatusCode.ERROR,
message: err instanceof Error ? err.message : 'Unknown error',
});
logger.error('Transcription exception', {
model,
error: err instanceof Error ? err.message : 'Unknown',
duration,
});
throw err;
} finally {
span.end();
}
});
}
}
// lib/tracing.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new NodeSDK({
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: 'deepgram-service',
[SemanticResourceAttributes.SERVICE_VERSION]: process.env.VERSION || '1.0.0',
[SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
}),
traceExporter: new OTLPTraceExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
}),
instrumentations: [
getNodeAutoInstrumentations({
'@opentelemetry/instrumentation-http': {
ignoreIncomingPaths: ['/health', '/metrics'],
},
}),
],
});
export function initTracing(): void {
sdk.start();
process.on('SIGTERM', () => {
sdk.shutdown()
.then(() => console.log('Tracing terminated'))
.catch((error) => console.error('Error terminating tracing', error))
.finally(() => process.exit(0));
});
}
// lib/logger.ts
import pino from 'pino';
export const logger = pino({
level: process.env.LOG_LEVEL || 'info',
formatters: {
level: (label) => ({ level: label }),
},
base: {
service: 'deepgram-service',
version: process.env.VERSION || '1.0.0',
environment: process.env.NODE_ENV || 'development',
},
timestamp: pino.stdTimeFunctions.isoTime,
});
// Specialized loggers
export const transcriptionLogger = logger.child({ component: 'transcription' });
export const metricsLogger = logger.child({ component: 'metrics' });
export const alertLogger = logger.child({ component: 'alerts' });
{
"dashboard": {
"title": "Deepgram Transcription Service",
"panels": [
{
"title": "Request Rate",
"type": "graph",
"targets": [
{
"expr": "sum(rate(deepgram_transcription_requests_total[5m])) by (status)",
"legendFormat": "{{status}}"
}
]
},
{
"title": "Latency (P95)",
"type": "graph",
"targets": [
{
"expr": "histogram_quantile(0.95, sum(rate(deepgram_transcription_latency_seconds_bucket[5m])) by (le, model))",
"legendFormat": "{{model}}"
}
]
},
{
"title": "Audio Processed (per hour)",
"type": "stat",
"targets": [
{
"expr": "sum(increase(deepgram_audio_processed_seconds_total[1h]))/60",
"legendFormat": "Minutes"
}
]
},
{
"title": "Error Rate",
"type": "gauge",
"targets": [
{
"expr": "sum(rate(deepgram_transcription_requests_total{status='error'}[5m])) / sum(rate(deepgram_transcription_requests_total[5m])) * 100"
}
]
},
{
"title": "Estimated Cost Today",
"type": "stat",
"targets": [
{
"expr": "sum(increase(deepgram_estimated_cost_dollars[24h]))"
}
]
},
{
"title": "Active Connections",
"type": "graph",
"targets": [
{
"expr": "deepgram_active_connections",
"legendFormat": "{{type}}"
}
]
}
]
}
}
# prometheus/rules/deepgram.yml