Claude Code & Datadog: APM und Infrastruktur-Monitoring einrichten

Produktionscode zu schreiben ist eine Sache. Zu wissen, was dieser Code im laufenden Betrieb tatsächlich tut — wie schnell, wie zuverlässig, wo er stockt — ist eine andere. Observability trennt professionelle Software-Teams von denen, die erst beim Kundenanruf von Problemen erfahren.

Datadog ist heute Standard für APM, Infrastruktur-Monitoring, Log-Management und synthetische Tests in einem. Dieser Artikel zeigt, wie du Datadog zusammen mit Claude Code in einen modernen Entwicklungsworkflow integrierst: vom ersten Tracer bis zu produktionsreifen Alerts — ohne API-Keys im Klartext und ohne unnötige Komplexität.

1. Datadog APM Setup: der richtige Einstieg

Datadog benötigt einen API-Key, um Daten an dein Konto zu senden. Dieser Key gehört niemals in den Quellcode — er gehört in eine Umgebungsvariable. Claude Code hält sich konsequent an dieses Prinzip: Wenn du es nach einem Datadog-Setup fragst, liest es den Key aus process.env.DD_API_KEY, nicht aus einem hartcodierten String.

# .env (nicht in Git committen, außer das Repo ist privat und du weißt was du tust)
DD_API_KEY=dein_key_hier
DD_APP_KEY=dein_app_key_hier
DD_SITE=datadoghq.eu   # für EU-Kunden

Der Datadog Agent läuft typischerweise als Sidecar (Docker) oder als systemd-Service auf dem Host. Für lokale Entwicklung reicht der Docker-Weg:

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc/:/host/proc/:ro \
  -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
  -e DD_API_KEY="${DD_API_KEY}" \
  -e DD_SITE="${DD_SITE}" \
  -e DD_APM_ENABLED=true \
  -e DD_LOGS_ENABLED=true \
  -p 8126:8126 \
  --name dd-agent \
  gcr.io/datadoghq/agent:7

2. Node.js Tracer initialisieren

Das dd-trace-Paket ist der offizielle Node.js-Tracer von Datadog. Die Initialisierung muss vor jedem anderen Import stehen — das ist kein Stilproblem, sondern eine technische Voraussetzung für Auto-Instrumentation.

// tracer.ts — eigene Datei, als erstes importieren
import tracer from 'dd-trace';

tracer.init({
  service: process.env.DD_SERVICE ?? 'mein-service',
  env: process.env.NODE_ENV ?? 'development',
  version: process.env.npm_package_version,
  logInjection: true,   // Korreliert Logs mit Traces
});

export default tracer;

// index.ts — Einstiegspunkt
import './tracer';       // MUSS als erstes kommen
import express from 'express';
// ... Rest der App

Claude Code erkennt dieses Muster zuverlässig: Wenn du es bittest, Datadog APM zu einem bestehenden Express- oder Fastify-Projekt hinzuzufügen, platziert es den Tracer-Import korrekt als ersten Import im Entry Point — nicht mittendrin im Code.

3. Python Tracer

Für Python-Projekte übernimmt ddtrace die Auto-Instrumentation. Der einfachste Weg ist das ddtrace-run-Wrapper-Kommando:

# Installation
pip install ddtrace

# Starten mit Auto-Instrumentation (Django, Flask, FastAPI werden erkannt)
DD_SERVICE=mein-service DD_ENV=production ddtrace-run python app.py

Für manuelle Kontrolle oder wenn der Wrapper nicht passt, geht auch die direkte Initialisierung im Code:

from ddtrace import tracer, patch_all
import os

patch_all()  # Instrumentiert requests, sqlalchemy, redis etc. automatisch

tracer.configure(
    hostname=os.getenv('DD_AGENT_HOST', 'localhost'),
    port=int(os.getenv('DD_TRACE_AGENT_PORT', 8126)),
)

4. Custom Spans und Tags

Auto-Instrumentation deckt HTTP-Requests, Datenbankabfragen und gängige Frameworks ab. Geschäftslogik — ein Checkout-Vorgang, eine PDF-Generierung, ein komplexer Berechnungsschritt — braucht manuelle Spans, damit du siehst, wo Zeit verloren geht.

// Node.js: manueller Span
import tracer from './tracer';

async function verarbeiteBestellung(bestellungId: string) {
  const span = tracer.startSpan('bestellung.verarbeiten');
  span.setTag('bestellung.id', bestellungId);

  try {
    const ergebnis = await holeBestellungAusDB(bestellungId);
    span.setTag('bestellung.wert', ergebnis.gesamtbetrag);
    return ergebnis;
  } catch (err) {
    span.setTag('error', true);
    span.setTag('error.message', (err as Error).message);
    throw err;
  } finally {
    span.finish();
  }
}

# Python: manueller Span mit Context Manager
from ddtrace import tracer

def verarbeite_bestellung(bestellung_id: str):
    with tracer.trace('bestellung.verarbeiten') as span:
        span.set_tag('bestellung.id', bestellung_id)
        ergebnis = hole_bestellung_aus_db(bestellung_id)
        span.set_tag('bestellung.wert', ergebnis['gesamtbetrag'])
        return ergebnis

Claude Code kann diese Spans auf Anfrage in bestehenden Code einfügen. Zeige ihm eine Funktion und schreibe: "Füge einen Datadog-Span hinzu, der die Dauer misst und bei Fehler ein Error-Tag setzt." Es wählt das richtige Pattern (Node.js vs. Python) und platziert span.finish() korrekt im finally-Block.

5. Log Management: strukturierte Logs

Datadog verarbeitet strukturierte JSON-Logs deutlich besser als Plaintext. Das wichtigste Detail: Wenn logInjection: true gesetzt ist, fügt der Tracer automatisch dd.trace_id und dd.span_id in Logs ein — so kannst du direkt vom Log in den zugehörigen Trace springen.

// Node.js mit Winston
import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()    // strukturierte Ausgabe
  ),
  transports: [
    new winston.transports.Console(),
  ],
});

// Datadog kann diese Logs automatisch parsen und mit Traces verknüpfen
logger.info('Bestellung verarbeitet', {
  bestellungId: '12345',
  dauer_ms: 142,
  status: 'erfolg',
});

6. Infrastructure Monitoring

Der Datadog Agent sammelt automatisch System-Metriken: CPU, Memory, Disk I/O, Netzwerk. Für Container-Umgebungen braucht er Zugriff auf den Docker Socket. Für Kubernetes läuft er als DaemonSet.

Custom Metrics — zum Beispiel Warteschlangentiefe, offene Verbindungen, Business-KPIs — sendet man über die StatsD-API, die der Agent auf Port 8125 bereitstellt:

// Node.js mit hot-shots (StatsD-Client)
import StatsD from 'hot-shots';

const dogstatsd = new StatsD({
  host: process.env.DD_AGENT_HOST ?? 'localhost',
  port: 8125,
  globalTags: {
    env: process.env.NODE_ENV ?? 'development',
    service: 'mein-service',
  },
});

// Gauge: aktueller Wert (z.B. Warteschlangenlänge)
dogstatsd.gauge('bestellungen.warteschlange', aktuelleWarteschlangenLaenge);

// Increment: Ereigniszähler
dogstatsd.increment('bestellungen.abgeschlossen');

// Histogram: Verteilung (z.B. Antwortzeiten)
dogstatsd.histogram('api.antwortzeit_ms', antwortZeitInMs);

7. Dashboards erstellen

Dashboards in Datadog lassen sich über die UI bauen oder per API definieren. Für reproduzierbare Setups ist die API besser — das Dashboard liegt dann als JSON in Git und kann in jedem Environment neu ausgerollt werden.

// Dashboard per API anlegen
const response = await fetch(
  `https://api.${process.env.DD_SITE}/api/v1/dashboard`,
  {
    method: 'POST',
    headers: {
      'DD-API-KEY': process.env.DD_API_KEY!,
      'DD-APPLICATION-KEY': process.env.DD_APP_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Service Overview',
      layout_type: 'ordered',
      widgets: [
        {
          definition: {
            type: 'timeseries',
            title: 'Request Rate',
            requests: [{
              q: `avg:trace.express.request.hits{service:mein-service}.as_rate()`,
            }],
          },
        },
        {
          definition: {
            type: 'timeseries',
            title: 'P99 Latency',
            requests: [{
              q: `p99:trace.express.request.duration{service:mein-service}`,
            }],
          },
        },
      ],
    }),
  }
);

Claude Code kann Dashboard-JSON auf Anfrage generieren. Beschreibe, welche Metriken du sehen möchtest, und es schreibt den API-Call — inklusive korrekt strukturierter Widget-Definitionen und der richtigen Metrik-Abfragen für dein Service-Setup.

8. Monitors und Alerts

Ein Monitor in Datadog überwacht eine Metrik oder einen Log-Stream und löst Alerts aus, wenn definierte Schwellwerte überschritten werden. Drei Monitore, die in jedem produktiven Service sinnvoll sind:

// Error-Rate Monitor: Alert wenn > 5% der Requests Fehler sind
{
  "name": "Hohe Fehlerrate – mein-service",
  "type": "metric alert",
  "query": "sum(last_5m):sum:trace.express.request.errors{service:mein-service}.as_rate() / sum:trace.express.request.hits{service:mein-service}.as_rate() * 100 > 5",
  "message": "Fehlerrate über 5% in den letzten 5 Minuten. @slack-alerts-channel",
  "thresholds": { "critical": 5, "warning": 2 },
  "notify_no_data": true,
  "no_data_timeframe": 10
}

• Error-Rate Monitor: Alert wenn Fehlerquote einen Schwellwert übersteigt
• Latenz-Monitor: Alert wenn P99-Antwortzeit einen Wert überschreitet
• No-Data Monitor: Alert wenn kein Traffic mehr ankommt (Service down)

9. Synthetics: Browser-Tests für Monitoring

Synthetic Monitoring führt automatisiert Browser-Tests gegen deine Produktionsumgebung aus — von Datadog-Servern weltweit. Das ist kein Ersatz für E2E-Tests in CI, sondern eine Ergänzung: Es prüft, ob deine Anwendung aus der Perspektive echter Nutzer erreichbar und funktionsfähig ist.

// API-Test per Synthetics API anlegen
const apiTest = {
  name: 'Checkout-Flow – Produktivumgebung',
  type: 'browser',
  config: {
    assertions: [
      { type: 'statusCode', operator: 'is', target: 200 },
      { type: 'responseTime', operator: 'lessThan', target: 2000 },
    ],
    request: {
      method: 'GET',
      url: 'https://meine-app.com/checkout',
    },
  },
  locations: ['aws:eu-central-1', 'aws:eu-west-1'],
  options: {
    tick_every: 300,  // Alle 5 Minuten
    min_failure_duration: 60,
    min_location_failed: 1,
  },
  message: 'Checkout nicht erreichbar! @pagerduty',
};

10. Kostenkontrolle

Datadog kann teuer werden, wenn man nicht aufpasst. Die größten Kostentreiber sind Custom Metrics (werden pro Metric-Name und Tag-Kombination abgerechnet) und Log-Volumen (wird nach ingested GB berechnet).

• Custom Metrics begrenzen: Hochkardinale Tags wie User-IDs oder Request-IDs niemals als Metric-Tags verwenden — jede Kombination ist eine eigene Metric und zählt zum Limit
• Log Sampling: Debug-Logs nur in Staging vollständig senden, in Produktion auf Error und Warning beschränken
• Retention konfigurieren: Datadog speichert Metriken standardmäßig 15 Monate — für Logs reichen oft 7 Tage. Retention in den Index-Einstellungen anpassen
• Exclusion Filter: Health-Check-Requests, Static-Asset-Calls und interne Monitoring-Calls aus APM herausfiltern — sie erzeugen Volumen, aber keine nützlichen Insights

// APM Exclusion Filter: Health-Checks nicht tracen
tracer.init({
  // ...
  ingestion: {
    sampleRate: 1.0,   // 100% aller Traces samplen
  },
});

// Bestimmte Routen vom Tracing ausschließen
app.get('/health', (req, res) => {
  // Vor dem Handler: Span manuell droppen
  const span = tracer.scope().active();
  if (span) span.context()._sampling.decision = 0;
  res.json({ status: 'ok' });
});

"Observability ist nicht das, was du einrichtest wenn etwas schiefgeht — es ist das, was dir sagt, dass etwas schiefgehen wird."

Claude Code beschleunigt diesen Setup erheblich: nicht weil es Datadog besser kennt als du, sondern weil es den Kontext deines Projekts sieht — welche Frameworks du nutzt, welche Routen existieren, wo Datenbankabfragen stattfinden. Es verbindet Datadog-Wissen mit deinem Code, statt Templates aus der Dokumentation zu kopieren.

Zwei verwandte Artikel, die dieses Thema ergänzen:

• Claude Code Debugging — Bugs finden, bevor Datadog sie meldet
• Claude Code für Unternehmen — Deployment, Zugriffskontrolle und Team-Workflows