Groq オブザーバビリティ

概要

Groqインテグレーション向けの包括的なオブザーバビリティをセットアップします。

前提条件

• PrometheusまたはPrometheusと互換性のあるメトリクスバックエンド
• OpenTelemetry SDKがインストール済み
• Grafanaまたはそれに類するダッシュボードツール
• AlertManagerが設定済み

メトリクス収集

主要メトリクス

メトリクス	タイプ	説明
groq_requests_total	カウンター	合計APIリクエスト
groq_request_duration_seconds	ヒストグラム	リクエストレイテンシ
groq_errors_total	カウンター	タイプ別のエラー数
groq_rate_limit_remaining	ゲージ	レート制限の余裕

Prometheusメトリクス

import { Registry, Counter, Histogram, Gauge } from 'prom-client';

const registry = new Registry();

const requestCounter = new Counter({
  name: 'groq_requests_total',
  help: 'Total Groq API requests',
  labelNames: ['method', 'status'],
  registers: [registry],
});

const requestDuration = new Histogram({
  name: 'groq_request_duration_seconds',
  help: 'Groq request duration',
  labelNames: ['method'],
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [registry],
});

const errorCounter = new Counter({
  name: 'groq_errors_total',
  help: 'Groq errors by type',
  labelNames: ['error_type'],
  registers: [registry],
});

インストルメント化されたクライアント

async function instrumentedRequest<T>(
  method: string,
  operation: () => Promise<T>
): Promise<T> {
  const timer = requestDuration.startTimer({ method });

  try {
    const result = await operation();
    requestCounter.inc({ method, status: 'success' });
    return result;
  } catch (error: any) {
    requestCounter.inc({ method, status: 'error' });
    errorCounter.inc({ error_type: error.code || 'unknown' });
    throw error;
  } finally {
    timer();
  }
}

分散トレーシング

OpenTelemetryセットアップ

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('groq-client');

async function tracedGroqCall<T>(
  operationName: string,
  operation: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(`groq.${operationName}`, async (span) => {
    try {
      const result = await operation();
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error: any) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      span.recordException(error);
      throw error;
    } finally {
      span.end();
    }
  });
}

ロギング戦略

構造化ログ

import pino from 'pino';

const logger = pino({
  name: 'groq',
  level: process.env.LOG_LEVEL || 'info',
});

function logGroqOperation(
  operation: string,
  data: Record<string, any>,
  duration: number
) {
  logger.info({
    service: 'groq',
    operation,
    duration_ms: duration,
    ...data,
  });
}

アラート設定

Prometheus AlertManagerルール

# groq_alerts.yaml
groups:
  - name: groq_alerts
    rules:
      - alert: GroqHighErrorRate
        expr: |
          rate(groq_errors_total[5m]) /
          rate(groq_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Groq error rate > 5%"

      - alert: GroqHighLatency
        expr: |
          histogram_quantile(0.95,
            rate(groq_request_duration_seconds_bucket[5m])
          ) > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Groq P95 latency > 2s"

      - alert: GroqDown
        expr: up{job="groq"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Groq integration is down"

ダッシュボード

Grafanaパネルクエリ

{
  "panels": [
    {
      "title": "Groq Request Rate",
      "targets": [{
        "expr": "rate(groq_requests_total[5m])"
      }]
    },
    {
      "title": "Groq Latency P50/P95/P99",
      "targets": [{
        "expr": "histogram_quantile(0.5, rate(groq_request_duration_seconds_bucket[5m]))"
      }]
    }
  ]
}

手順

ステップ1: メトリクス収集をセットアップ

主要な操作向けのPrometheusカウンター、ヒストグラム、ゲージを実装します。

ステップ2: 分散トレーシングを追加

エンドツーエンドのリクエストトレーシング向けにOpenTelemetryを統合します。

ステップ3: 構造化ログを設定

一貫したフィールド名でJSONログをセットアップします。

ステップ4: アラートルールを作成

エラー率とレイテンシ向けのPrometheusアラートルールを定義します。

出力

• メトリクス収集が有効
• 分散トレーシングが設定済み
• 構造化ログが実装済み
• アラートルールがデプロイ済み

エラーハンドリング

問題	原因	解決方法
メトリクス欠落	インストルメンテーションなし	クライアント呼び出しをラップ
トレースギャップ	伝播がない	コンテキストヘッダーを確認
アラート多発	閾値が不適切	アラートルールを調整
高カーディナリティ	ラベルが多すぎる	ラベル値を削減

例

クイックメトリクスエンドポイント

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', registry.contentType);
  res.send(await registry.metrics());
});

リソース

• Prometheus ベストプラクティス
• OpenTelemetry ドキュメント
• Groq オブザーバビリティガイド

次のステップ

インシデント対応については、groq-incident-runbookを参照してください。