Node.js'de Gözlemlenebilirlik: Karmaşıklık Olmadan Loglar, Metrikler ve İzler

// Yazdığınız şey
console.log("User login failed", email, error.message);
 
// Log dosyanızda ortaya çıkan şey
// User login failed john@example.com ECONNREFUSED
 
// Şimdi şunu deneyin:
// 1. Son bir saatteki tüm giriş başarısızlıklarını arama
// 2. Kullanıcı başına başarısızlıkları sayma
// 3. Sadece ECONNREFUSED hatalarını filtreleme
// 4. Bunu tetikleyen istekle ilişkilendirme
// İyi şanslar. Yapılandırılmamış bir string. Metin içinde grep yapıyorsunuz.

// Yapılandırılmış loglama neye benzer
{
  "level": 50,
  "time": 1709312587000,
  "msg": "User login failed",
  "email": "john@example.com",
  "error": "ECONNREFUSED",
  "requestId": "req-abc-123",
  "route": "POST /api/auth/login",
  "responseTime": 1247,
  "pid": 12345
}

// src/lib/logger.ts
import pino from "pino";
 
const isProduction = process.env.NODE_ENV === "production";
 
export const logger = pino({
  level: process.env.LOG_LEVEL || (isProduction ? "info" : "debug"),
  // Üretimde sadece stdout'a JSON. PM2/container runtime gerisini halleder.
  // Geliştirmede, insan tarafından okunabilir çıktı için pino-pretty kullanın.
  ...(isProduction
    ? {}
    : {
        transport: {
          target: "pino-pretty",
          options: {
            colorize: true,
            translateTime: "HH:MM:ss",
            ignore: "pid,hostname",
          },
        },
      }),
  // Her log satırındaki standart alanlar
  base: {
    service: process.env.SERVICE_NAME || "api",
    version: process.env.APP_VERSION || "unknown",
  },
  // Error nesnelerini düzgün serileştir
  serializers: {
    err: pino.stdSerializers.err,
    error: pino.stdSerializers.err,
    req: pino.stdSerializers.req,
    res: pino.stdSerializers.res,
  },
  // Hassas alanları gizle
  redact: {
    paths: ["req.headers.authorization", "req.headers.cookie", "password", "creditCard", "ssn"],
    censor: "[REDACTED]",
  },
});

// FATAL (60) - Süreç çökmek üzere. Birini uyandırın.
logger.fatal({ err }, "Unrecoverable database connection failure");
 
// ERROR (50) - Olmaması gereken bir şey başarısız oldu. Yakında araştırın.
logger.error({ err, userId, orderId }, "Payment processing failed");
 
// WARN (40) - Beklenmedik ama yönetilen bir durum. Göz kulak olun.
logger.warn({ retryCount: 3, service: "email" }, "Retry limit approaching");
 
// INFO (30) - Kaydedilmeye değer normal işlemler. "Ne oldu" logu.
logger.info({ userId, action: "login" }, "User authenticated");
 
// DEBUG (20) - Hata ayıklama için ayrıntılı bilgi. Asla üretimde değil.
logger.debug({ query, params }, "Database query executing");
 
// TRACE (10) - Son derece ayrıntılı. Sadece çaresiz kaldığınızda.
logger.trace({ headers: req.headers }, "Incoming request headers");

// Bu alt loggerdan gelen her log userId ve sessionId içerecek
const userLogger = logger.child({ userId: "usr_4821", sessionId: "ses_xyz" });
 
userLogger.info("User viewed dashboard");
// Çıktı userId ve sessionId'yi otomatik olarak içerir
 
userLogger.info({ page: "/settings" }, "User navigated");
// Çıktı userId, sessionId VE page içerir

// src/middleware/request-logger.ts
import { randomUUID } from "node:crypto";
import { logger } from "../lib/logger";
import type { Request, Response, NextFunction } from "express";
 
export function requestLogger(req: Request, res: Response, next: NextFunction) {
  const requestId = req.headers["x-request-id"]?.toString() || randomUUID();
  const startTime = performance.now();
 
  // İsteğe bir alt logger ekle
  req.log = logger.child({
    requestId,
    method: req.method,
    url: req.originalUrl,
    userAgent: req.headers["user-agent"],
    ip: req.headers["x-forwarded-for"]?.toString().split(",").pop()?.trim() || req.socket.remoteAddress,
  });
 
  // Korelasyon için yanıtta istek ID header'ını ayarla
  res.setHeader("x-request-id", requestId);
 
  req.log.info("Request received");
 
  res.on("finish", () => {
    const duration = Math.round(performance.now() - startTime);
    const logMethod = res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info";
 
    req.log[logMethod](
      {
        statusCode: res.statusCode,
        duration,
        contentLength: res.getHeader("content-length"),
      },
      "Request completed",
    );
  });
 
  next();
}

// src/lib/async-context.ts
import { AsyncLocalStorage } from "node:async_hooks";
import { logger } from "./logger";
import type { Logger } from "pino";
 
interface RequestContext {
  requestId: string;
  logger: Logger;
  userId?: string;
  startTime: number;
}
 
export const asyncContext = new AsyncLocalStorage<RequestContext>();
 
// Çağrı yığınının herhangi bir yerinden bağlamsal logger'ı al
export function getLogger(): Logger {
  const store = asyncContext.getStore();
  return store?.logger || logger;
}
 
export function getRequestId(): string | undefined {
  return asyncContext.getStore()?.requestId;
}

// src/middleware/async-context-middleware.ts
import { randomUUID } from "node:crypto";
import { asyncContext } from "../lib/async-context";
import { logger } from "../lib/logger";
import type { Request, Response, NextFunction } from "express";
 
export function asyncContextMiddleware(req: Request, res: Response, next: NextFunction) {
  const requestId = req.headers["x-request-id"]?.toString() || randomUUID();
  const requestLogger = logger.child({ requestId });
 
  const context = {
    requestId,
    logger: requestLogger,
    startTime: performance.now(),
  };
 
  asyncContext.run(context, () => {
    res.setHeader("x-request-id", requestId);
    next();
  });
}

// src/services/order-service.ts
import { getLogger } from "../lib/async-context";
 
export async function processOrder(orderId: string) {
  const log = getLogger(); // Otomatik olarak requestId ekli!
 
  log.info({ orderId }, "Processing order");
 
  const items = await fetchOrderItems(orderId);
  log.debug({ itemCount: items.length }, "Order items fetched");
 
  const total = calculateTotal(items);
  log.info({ orderId, total }, "Order processed successfully");
 
  return { orderId, total, items };
}
 
// Logger'ı parametre olarak geçirmeye gerek yok. Sadece çalışıyor.

# Logları gerçek zamanlı görüntüle
pm2 logs api --lines 100
 
# Loglar ~/.pm2/logs/ konumunda saklanır
# api-out.log  — stdout (JSON loglarınız)
# api-error.log — stderr (yakalanmamış istisnalar, yığın izleri)

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 14
pm2 set pm2-logrotate:compress true

# /etc/promtail/config.yml
server:
  http_listen_port: 9080
 
positions:
  filename: /tmp/positions.yaml
 
clients:
  - url: http://loki:3100/loki/api/v1/push
 
scrape_configs:
  - job_name: node-api
    static_configs:
      - targets:
          - localhost
        labels:
          job: node-api
          environment: production
          __path__: /home/deploy/.pm2/logs/api-out.log
    pipeline_stages:
      - json:
          expressions:
            level: level
            msg: msg
            service: service
      - labels:
          level:
          service:
      - timestamp:
          source: time
          format: UnixMs

// ÜRETİMDE YANLIŞ — çok satırlı JSON, satır tabanlı işlemeyi bozar
{
  "level": 30,
  "time": 1709312587000,
  "msg": "Request completed"
}
 
// ÜRETİMDE DOĞRU — NDJSON, satır başına bir nesne
{"level":30,"time":1709312587000,"msg":"Request completed"}

// "Kaç istek sunduk?"
const httpRequestsTotal = new Counter({
  name: "http_requests_total",
  help: "Total number of HTTP requests",
  labelNames: ["method", "route", "status_code"],
});

// "Şu anda kaç bağlantı aktif?"
const activeConnections = new Gauge({
  name: "active_connections",
  help: "Number of currently active connections",
});

// "İstekler ne kadar sürüyor?" 10ms, 50ms, 100ms vb. kovalarla
const httpRequestDuration = new Histogram({
  name: "http_request_duration_seconds",
  help: "Duration of HTTP requests in seconds",
  labelNames: ["method", "route", "status_code"],
  buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
});

// src/lib/metrics.ts
import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from "prom-client";
 
// Global olanı kirletmemek için özel bir kayıt defteri oluştur
export const metricsRegistry = new Registry();
 
// Varsayılan Node.js metriklerini topla:
// - process_cpu_seconds_total
// - process_resident_memory_bytes
// - nodejs_heap_size_total_bytes
// - nodejs_active_handles_total
// - nodejs_eventloop_lag_seconds
// - nodejs_gc_duration_seconds
collectDefaultMetrics({
  register: metricsRegistry,
  prefix: "nodeapp_",
  // Her 10 saniyede topla
  gcDurationBuckets: [0.001, 0.01, 0.1, 1, 2, 5],
});
 
// --- HTTP Metrikleri ---
 
export const httpRequestsTotal = new Counter({
  name: "nodeapp_http_requests_total",
  help: "Total number of HTTP requests received",
  labelNames: ["method", "route", "status_code"] as const,
  registers: [metricsRegistry],
});
 
export const httpRequestDuration = new Histogram({
  name: "nodeapp_http_request_duration_seconds",
  help: "Duration of HTTP requests in seconds",
  labelNames: ["method", "route", "status_code"] as const,
  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  registers: [metricsRegistry],
});
 
export const httpRequestSizeBytes = new Histogram({
  name: "nodeapp_http_request_size_bytes",
  help: "Size of HTTP request bodies in bytes",
  labelNames: ["method", "route"] as const,
  buckets: [100, 1000, 10000, 100000, 1000000],
  registers: [metricsRegistry],
});
 
// --- İş Metrikleri ---
 
export const ordersProcessed = new Counter({
  name: "nodeapp_orders_processed_total",
  help: "Total number of orders processed",
  labelNames: ["status"] as const, // "success", "failed", "refunded"
  registers: [metricsRegistry],
});
 
export const activeWebSocketConnections = new Gauge({
  name: "nodeapp_active_websocket_connections",
  help: "Number of active WebSocket connections",
  registers: [metricsRegistry],
});
 
export const externalApiDuration = new Histogram({
  name: "nodeapp_external_api_duration_seconds",
  help: "Duration of external API calls",
  labelNames: ["service", "endpoint", "status"] as const,
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30],
  registers: [metricsRegistry],
});
 
export const dbQueryDuration = new Histogram({
  name: "nodeapp_db_query_duration_seconds",
  help: "Duration of database queries",
  labelNames: ["operation", "table"] as const,
  buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5],
  registers: [metricsRegistry],
});

// src/middleware/metrics-middleware.ts
import { httpRequestsTotal, httpRequestDuration } from "../lib/metrics";
import type { Request, Response, NextFunction } from "express";
 
// Kardinalite patlamasını önlemek için rotaları normalleştir
// /api/users/123 → /api/users/:id
// Bu olmadan Prometheus her kullanıcı ID'si için yeni bir zaman serisi oluşturacak
function normalizeRoute(req: Request): string {
  const route = req.route?.path || req.path;
 
  // Yaygın dinamik segmentleri değiştir
  return route
    .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, "/:uuid")
    .replace(/\/\d+/g, "/:id")
    .replace(/\/[a-f0-9]{24}/g, "/:objectId");
}
 
export function metricsMiddleware(req: Request, res: Response, next: NextFunction) {
  // Metrik uç noktasının kendisi için metrikleri izleme
  if (req.path === "/metrics") {
    return next();
  }
 
  const end = httpRequestDuration.startTimer();
 
  res.on("finish", () => {
    const route = normalizeRoute(req);
    const labels = {
      method: req.method,
      route,
      status_code: res.statusCode.toString(),
    };
 
    httpRequestsTotal.inc(labels);
    end(labels);
  });
 
  next();
}

// src/routes/metrics.ts
import { Router } from "express";
import { metricsRegistry } from "../lib/metrics";
 
const router = Router();
 
router.get("/metrics", async (req, res) => {
  // Temel auth koruması — metrikleri herkese açık gösterme
  const authHeader = req.headers.authorization;
  const expected = `Basic ${Buffer.from(`${process.env.METRICS_USER}:${process.env.METRICS_PASSWORD}`).toString(
    "base64",
  )}`;
 
  if (!authHeader || authHeader !== expected) {
    res.status(401).set("WWW-Authenticate", "Basic").send("Unauthorized");
    return;
  }
 
  try {
    const metrics = await metricsRegistry.metrics();
    res.set("Content-Type", metricsRegistry.contentType);
    res.send(metrics);
  } catch (err) {
    res.status(500).send("Error collecting metrics");
  }
});
 
export default router;

// Sipariş servisinizde
import { ordersProcessed, externalApiDuration } from "../lib/metrics";
 
export async function processOrder(order: Order) {
  try {
    // Ödeme sağlayıcı çağrısını zamanlayın
    const paymentTimer = externalApiDuration.startTimer({
      service: "stripe",
      endpoint: "charges.create",
    });
 
    const charge = await stripe.charges.create({
      amount: order.total,
      currency: "usd",
      source: order.paymentToken,
    });
 
    paymentTimer({ status: "success" });
 
    ordersProcessed.inc({ status: "success" });
    return charge;
  } catch (err) {
    ordersProcessed.inc({ status: "failed" });
 
    externalApiDuration.startTimer({
      service: "stripe",
      endpoint: "charges.create",
    })({ status: "error" });
 
    throw err;
  }
}

rate(nodeapp_http_requests_total[5m])

100 * (
  sum(rate(nodeapp_http_requests_total{status_code=~"5.."}[5m]))
  /
  sum(rate(nodeapp_http_requests_total[5m]))
)

histogram_quantile(0.99,
  sum(rate(nodeapp_http_request_duration_seconds_bucket[5m])) by (le)
)

nodeapp_nodejs_eventloop_lag_seconds{quantile="0.99"}

nodeapp_nodejs_heap_size_used_bytes / nodeapp_nodejs_heap_size_total_bytes * 100

nodeapp_nodejs_active_handles_total

# /etc/grafana/provisioning/dashboards/dashboards.yml
apiVersion: 1
providers:
  - name: "Node.js Services"
    orgId: 1
    folder: "Services"
    type: file
    disableDeletion: false
    editable: true
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

// src/instrumentation.ts
// Bu dosya diğer tüm import'lardan ÖNCE yüklenmelidir.
// Node.js'de --require veya --import flag'ini kullanın.
 
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { Resource } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 
const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: process.env.SERVICE_NAME || "node-api",
    [ATTR_SERVICE_VERSION]: process.env.APP_VERSION || "0.0.0",
    "deployment.environment": process.env.NODE_ENV || "development",
  }),
 
  // İzleri toplayıcınıza gönderin (Jaeger, Tempo, vb.)
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318/v1/traces",
  }),
 
  // İsteğe bağlı olarak metrikleri de OTel üzerinden gönderin
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318/v1/metrics",
    }),
    exportIntervalMillis: 15000,
  }),
 
  // Otomatik enstrümantasyon: otomatik olarak
  // HTTP istekleri, Express rotaları, PostgreSQL sorguları, Redis komutları,
  // DNS aramaları ve daha fazlası için span'lar oluşturur
  instrumentations: [
    getNodeAutoInstrumentations({
      // Gürültülü enstrümantasyonları devre dışı bırak
      "@opentelemetry/instrumentation-fs": { enabled: false },
      "@opentelemetry/instrumentation-dns": { enabled: false },
      // Belirli olanları yapılandır
      "@opentelemetry/instrumentation-http": {
        ignoreIncomingPaths: ["/health", "/ready", "/metrics"],
      },
      "@opentelemetry/instrumentation-express": {
        ignoreLayersType: ["middleware"],
      },
    }),
  ],
});
 
sdk.start();
 
// Zarif kapanış
process.on("SIGTERM", () => {
  sdk.shutdown().then(
    () => console.log("OTel SDK shut down successfully"),
    (err) => console.error("Error shutting down OTel SDK", err),
  );
});

node --import ./src/instrumentation.ts ./src/server.ts

// src/services/order-service.ts
import { trace, SpanStatusCode } from "@opentelemetry/api";
 
const tracer = trace.getTracer("order-service");
 
export async function processOrder(orderId: string): Promise<Order> {
  return tracer.startActiveSpan("processOrder", async (span) => {
    try {
      span.setAttribute("order.id", orderId);
 
      // Bu span, bu fonksiyonların içindeki otomatik enstrümante edilmiş
      // DB sorgularının veya HTTP çağrılarının ebeveyni olur
      const order = await fetchOrder(orderId);
      span.setAttribute("order.total", order.total);
      span.setAttribute("order.item_count", order.items.length);
 
      const validationResult = await tracer.startActiveSpan("validateOrder", async (validationSpan) => {
        const result = await validateInventory(order);
        validationSpan.setAttribute("validation.passed", result.valid);
        if (!result.valid) {
          validationSpan.setStatus({
            code: SpanStatusCode.ERROR,
            message: `Validation failed: ${result.reason}`,
          });
        }
        validationSpan.end();
        return result;
      });
 
      if (!validationResult.valid) {
        span.setStatus({
          code: SpanStatusCode.ERROR,
          message: "Order validation failed",
        });
        throw new Error(validationResult.reason);
      }
 
      const payment = await processPayment(order);
      span.setAttribute("payment.id", payment.id);
 
      span.setStatus({ code: SpanStatusCode.OK });
      return order;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: (err as Error).message,
      });
      throw err;
    } finally {
      span.end();
    }
  });
}

import { context, propagation } from "@opentelemetry/api";
 
// Mesaj yayınlarken
function publishEvent(queue: string, payload: object) {
  const carrier: Record<string, string> = {};
 
  // Mevcut iz bağlamını taşıyıcıya enjekte et
  propagation.inject(context.active(), carrier);
 
  // Hem yükü hem de iz bağlamını gönder
  messageQueue.publish(queue, {
    payload,
    traceContext: carrier,
  });
}
 
// Mesaj tüketirken
function consumeEvent(message: QueueMessage) {
  // İz bağlamını mesajdan çıkar
  const parentContext = propagation.extract(context.active(), message.traceContext);
 
  // İşleyiciyi çıkarılan bağlam içinde çalıştır
  // Artık burada oluşturulan tüm span'lar orijinal izin çocukları olacak
  context.with(parentContext, () => {
    tracer.startActiveSpan("processEvent", (span) => {
      span.setAttribute("queue.message_id", message.id);
      handleEvent(message.payload);
      span.end();
    });
  });
}

# docker-compose.otel.yml
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686" # Jaeger UI
      - "4318:4318" # OTLP HTTP alıcısı
    environment:
      - COLLECTOR_OTLP_ENABLED=true

// src/routes/health.ts
import { Router } from "express";
import { Pool } from "pg";
import Redis from "ioredis";
 
const router = Router();
 
interface HealthCheckResult {
  status: "ok" | "degraded" | "error";
  checks: Record<
    string,
    {
      status: "ok" | "error";
      latency?: number;
      message?: string;
    }
  >;
  uptime: number;
  timestamp: string;
  version: string;
}
 
async function checkDatabase(pool: Pool): Promise<{ ok: boolean; latency: number }> {
  const start = performance.now();
  try {
    await pool.query("SELECT 1");
    return { ok: true, latency: Math.round(performance.now() - start) };
  } catch {
    return { ok: false, latency: Math.round(performance.now() - start) };
  }
}
 
async function checkRedis(redis: Redis): Promise<{ ok: boolean; latency: number }> {
  const start = performance.now();
  try {
    await redis.ping();
    return { ok: true, latency: Math.round(performance.now() - start) };
  } catch {
    return { ok: false, latency: Math.round(performance.now() - start) };
  }
}
 
export function createHealthRoutes(pool: Pool, redis: Redis) {
  // Canlılık — sadece sürecin yanıt verip vermediğini kontrol et
  router.get("/live", (_req, res) => {
    res.status(200).json({ status: "ok" });
  });
 
  // Hazırlık — tüm bağımlılıkları kontrol et
  router.get("/ready", async (_req, res) => {
    const [db, cache] = await Promise.all([checkDatabase(pool), checkRedis(redis)]);
 
    const allOk = db.ok && cache.ok;
 
    res.status(allOk ? 200 : 503).json({
      status: allOk ? "ok" : "not_ready",
      checks: {
        database: db,
        redis: cache,
      },
    });
  });
 
  // Tam sağlık — panolar ve hata ayıklama için ayrıntılı durum
  router.get("/health", async (_req, res) => {
    const [db, cache] = await Promise.all([checkDatabase(pool), checkRedis(redis)]);
 
    const anyError = !db.ok || !cache.ok;
    const allError = !db.ok && !cache.ok;
 
    const result: HealthCheckResult = {
      status: allError ? "error" : anyError ? "degraded" : "ok",
      checks: {
        database: {
          status: db.ok ? "ok" : "error",
          latency: db.latency,
          ...(!db.ok && { message: "Connection failed" }),
        },
        redis: {
          status: cache.ok ? "ok" : "error",
          latency: cache.latency,
          ...(!cache.ok && { message: "Connection failed" }),
        },
      },
      uptime: process.uptime(),
      timestamp: new Date().toISOString(),
      version: process.env.APP_VERSION || "unknown",
    };
 
    // ok/degraded için 200 döndür (servis hala bazı trafiği karşılayabilir)
    // error için 503 döndür (servis rotasyondan çıkarılmalı)
    res.status(result.status === "error" ? 503 : 200).json(result);
  });
 
  return router;
}

# k8s/deployment.yml
spec:
  containers:
    - name: api
      livenessProbe:
        httpGet:
          path: /live
          port: 3000
        initialDelaySeconds: 10
        periodSeconds: 15
        timeoutSeconds: 5
        failureThreshold: 3 # 3 ardışık başarısızlıktan sonra yeniden başlat (45s)
      readinessProbe:
        httpGet:
          path: /ready
          port: 3000
        initialDelaySeconds: 5
        periodSeconds: 10
        timeoutSeconds: 5
        failureThreshold: 2 # 2 başarısızlıktan sonra LB'den çıkar (20s)
      startupProbe:
        httpGet:
          path: /ready
          port: 3000
        initialDelaySeconds: 0
        periodSeconds: 5
        failureThreshold: 30 # Başlangıç için 150s'ye kadar süre ver

// src/lib/sentry.ts
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
 
export function initSentry() {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV || "development",
    release: process.env.APP_VERSION || "unknown",
 
    // Performans izleme için işlemlerin %10'unu örnekle
    // (geliştirmede %100)
    tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
 
    // Örneklenen işlemlerin %100'ünü profille
    profilesSampleRate: 1.0,
 
    integrations: [
      nodeProfilingIntegration(),
      // Gürültülü hataları filtrele
      Sentry.rewriteFramesIntegration({
        root: process.cwd(),
      }),
    ],
 
    // Geliştirmeden hata gönderme
    enabled: process.env.NODE_ENV === "production",
 
    // Bilinen sorun olmayanları filtrele
    ignoreErrors: [
      // İstemci bağlantı kesintileri hata değil
      "ECONNRESET",
      "ECONNABORTED",
      "EPIPE",
      // Botlar çöp gönderiyor
      "SyntaxError: Unexpected token",
    ],
 
    // Göndermeden önce kişisel verileri temizle
    beforeSend(event) {
      // IP adreslerini kaldır
      if (event.request) {
        delete event.request.headers?.["x-forwarded-for"];
        delete event.request.headers?.["x-real-ip"];
        delete event.request.cookies;
      }
 
      // Hassas sorgu parametrelerini kaldır
      if (event.request?.query_string) {
        const params = new URLSearchParams(event.request.query_string);
        params.delete("token");
        params.delete("api_key");
        event.request.query_string = params.toString();
      }
 
      return event;
    },
  });
}

// src/middleware/error-handler.ts
import * as Sentry from "@sentry/node";
import { getLogger } from "../lib/async-context";
import type { Request, Response, NextFunction } from "express";
 
// Sentry istek işleyicisi ilk gelmelidir
export const sentryRequestHandler = Sentry.Handlers.requestHandler();
 
// Sentry izleme işleyicisi
export const sentryTracingHandler = Sentry.Handlers.tracingHandler();
 
// Özel hata işleyiciniz en son gelir
export function errorHandler(err: Error, req: Request, res: Response, _next: NextFunction) {
  const log = getLogger();
 
  // Sentry olayına özel bağlam ekle
  Sentry.withScope((scope) => {
    scope.setTag("route", req.route?.path || req.path);
    scope.setTag("method", req.method);
 
    if (req.user) {
      scope.setUser({
        id: req.user.id,
        // E-posta veya kullanıcı adını Sentry'ye gönderme
      });
    }
 
    // Hata ayıklama için breadcrumb'lar ekle
    scope.addBreadcrumb({
      category: "request",
      message: `${req.method} ${req.path}`,
      level: "info",
      data: {
        query: req.query,
        statusCode: res.statusCode,
      },
    });
 
    Sentry.captureException(err);
  });
 
  // Tam bağlamla hatayı logla
  log.error(
    {
      err,
      statusCode: 500,
      route: req.route?.path || req.path,
      method: req.method,
    },
    "Unhandled error in request handler",
  );
 
  // Genel bir hata yanıtı gönder
  // Üretimde asla hata ayrıntılarını istemciye açıklama
  res.status(500).json({
    error: "Internal Server Error",
    ...(process.env.NODE_ENV !== "production" && {
      message: err.message,
      stack: err.stack,
    }),
  });
}

# CI/CD pipeline'ınızda
npx @sentry/cli sourcemaps upload \
  --org your-org \
  --project your-project \
  --release $APP_VERSION \
  ./dist

// vite.config.ts (veya eşdeğeri)
import { sentryVitePlugin } from "@sentry/vite-plugin";
 
export default defineConfig({
  build: {
    sourcemap: true, // Sentry için gerekli
  },
  plugins: [
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

// src/server.ts — giriş noktanızın başına yakın
 
process.on("unhandledRejection", (reason, promise) => {
  logger.fatal({ reason, promise }, "Unhandled promise rejection — crashing");
  Sentry.captureException(reason);
 
  // Çökmeden önce Sentry olaylarını temizle
  Sentry.flush(2000).finally(() => {
    process.exit(1);
  });
});
 
process.on("uncaughtException", (error) => {
  logger.fatal({ err: error }, "Uncaught exception — crashing");
  Sentry.captureException(error);
 
  Sentry.flush(2000).finally(() => {
    process.exit(1);
  });
});

# alertmanager.yml
global:
  resolve_timeout: 5m
  slack_api_url: $SLACK_WEBHOOK_URL
 
route:
  receiver: "slack-warnings"
  group_by: ["alertname", "service"]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  routes:
    - match:
        severity: critical
      receiver: "pagerduty-critical"
      repeat_interval: 15m
    - match:
        severity: warning
      receiver: "slack-warnings"
 
receivers:
  - name: "pagerduty-critical"
    pagerduty_configs:
      - routing_key: $PAGERDUTY_ROUTING_KEY
        severity: critical
  - name: "slack-warnings"
    slack_configs:
      - channel: "#alerts"
        title: '{{ template "slack.title" . }}'
        text: '{{ template "slack.text" . }}'

# prometheus/rules/node-api.yml
groups:
  - name: node-api-critical
    rules:
      # Yüksek hata oranı — bir şey bozuk
      - alert: HighErrorRate
        expr: |
          (
            sum(rate(nodeapp_http_requests_total{status_code=~"5.."}[5m]))
            /
            sum(rate(nodeapp_http_requests_total[5m]))
          ) > 0.01
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Error rate above 1% for 5 minutes"
          description: "{{ $value | humanizePercentage }} of requests are returning 5xx"
 
      # Yavaş yanıtlar — kullanıcılar acı çekiyor
      - alert: HighP99Latency
        expr: |
          histogram_quantile(0.99,
            sum(rate(nodeapp_http_request_duration_seconds_bucket[5m])) by (le)
          ) > 1
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "p99 latency above 1 second for 5 minutes"
          description: "p99 latency is {{ $value | humanizeDuration }}"
 
      # Bellek sızıntısı — yakında OOM olacak
      - alert: HighHeapUsage
        expr: |
          (
            nodeapp_nodejs_heap_size_used_bytes
            /
            nodeapp_nodejs_heap_size_total_bytes
          ) > 0.80
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "Heap usage above 80% for 10 minutes"
          description: "Heap usage is at {{ $value | humanizePercentage }}"
 
      # Süreç çökmüş
      - alert: ServiceDown
        expr: up{job="node-api"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Node.js API is down"
 
  - name: node-api-warnings
    rules:
      # Olay döngüsü yavaşlıyor
      - alert: HighEventLoopLag
        expr: |
          nodeapp_nodejs_eventloop_lag_seconds{quantile="0.99"} > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Event loop lag above 100ms"
          description: "p99 event loop lag is {{ $value | humanizeDuration }}"
 
      # Trafik önemli ölçüde düştü — olası yönlendirme sorunu
      - alert: TrafficDrop
        expr: |
          sum(rate(nodeapp_http_requests_total[5m]))
          < (sum(rate(nodeapp_http_requests_total[5m] offset 1h)) * 0.5)
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Traffic dropped by more than 50% compared to 1 hour ago"
 
      # Veritabanı sorguları yavaşlıyor
      - alert: SlowDatabaseQueries
        expr: |
          histogram_quantile(0.99,
            sum(rate(nodeapp_db_query_duration_seconds_bucket[5m])) by (le, operation)
          ) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "p99 database query time above 500ms"
          description: "Slow {{ $labels.operation }} queries: {{ $value | humanizeDuration }}"
 
      # Harici API başarısız oluyor
      - alert: ExternalAPIFailures
        expr: |
          (
            sum(rate(nodeapp_external_api_duration_seconds_count{status="error"}[5m])) by (service)
            /
            sum(rate(nodeapp_external_api_duration_seconds_count[5m])) by (service)
          ) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "External API {{ $labels.service }} failing >10%"

// src/server.ts
import { initSentry } from "./lib/sentry";
 
// Sentry'yi ilk olarak başlat — diğer import'lardan önce
initSentry();
 
import express from "express";
import * as Sentry from "@sentry/node";
import { Pool } from "pg";
import Redis from "ioredis";
import { logger } from "./lib/logger";
import { asyncContextMiddleware } from "./middleware/async-context-middleware";
import { metricsMiddleware } from "./middleware/metrics-middleware";
import { requestLogger } from "./middleware/request-logger";
import { sentryRequestHandler, sentryTracingHandler, errorHandler } from "./middleware/error-handler";
import { createHealthRoutes } from "./routes/health";
import metricsRouter from "./routes/metrics";
import apiRouter from "./routes/api";
 
const app = express();
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const redis = new Redis(process.env.REDIS_URL);
 
// --- Ara Katman Sırası Önemli ---
 
// 1. Sentry istek işleyicisi (ilk olmalı)
app.use(sentryRequestHandler);
app.use(sentryTracingHandler);
 
// 2. Asenkron bağlam (istek kapsamlı bağlam oluşturur)
app.use(asyncContextMiddleware);
 
// 3. İstek loglama
app.use(requestLogger);
 
// 4. Metrik toplama
app.use(metricsMiddleware);
 
// 5. Gövde ayrıştırma
app.use(express.json({ limit: "1mb" }));
 
// --- Rotalar ---
 
// Sağlık kontrolleri (auth gerekmez)
app.use(createHealthRoutes(pool, redis));
 
// Metrikler (temel auth korumalı)
app.use(metricsRouter);
 
// API rotaları
app.use("/api", apiRouter);
 
// --- Hata İşleme ---
 
// Sentry hata işleyicisi (özel hata işleyiciden önce olmalı)
app.use(Sentry.Handlers.errorHandler());
 
// Özel hata işleyici (en son olmalı)
app.use(errorHandler);
 
// --- Başlat ---
 
const port = parseInt(process.env.PORT || "3000", 10);
 
app.listen(port, () => {
  logger.info(
    {
      port,
      nodeEnv: process.env.NODE_ENV,
      version: process.env.APP_VERSION,
    },
    "Server started",
  );
});
 
// Zarif kapanış
async function shutdown(signal: string) {
  logger.info({ signal }, "Shutdown signal received");
 
  // Yeni bağlantıları kabul etmeyi durdur
  // Devam eden istekleri işle (Express bunu otomatik yapar)
 
  // Veritabanı havuzunu kapat
  await pool.end().catch((err) => {
    logger.error({ err }, "Error closing database pool");
  });
 
  // Redis bağlantısını kapat
  await redis.quit().catch((err) => {
    logger.error({ err }, "Error closing Redis connection");
  });
 
  // Sentry'yi temizle
  await Sentry.close(2000);
 
  logger.info("Shutdown complete");
  process.exit(0);
}
 
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

// Bu minimal kurulum. 50 satırın altında. Bahane yok.
import pino from "pino";
import express from "express";
import * as Sentry from "@sentry/node";
 
const logger = pino({ level: "info" });
const app = express();
 
Sentry.init({ dsn: process.env.SENTRY_DSN });
app.use(Sentry.Handlers.requestHandler());
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok", uptime: process.uptime() });
});
 
app.use("/api", apiRoutes);
 
app.use(Sentry.Handlers.errorHandler());
app.use((err: Error, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
  logger.error({ err }, "Unhandled error");
  res.status(500).json({ error: "Internal Server Error" });
});
 
app.listen(3000, () => logger.info("Server started on port 3000"));