fullstack.org.ua

Distributed Tracing · fullstack.org.ua

Середній18 хв· Fullstack Team

Distributed Tracing

Дізнайтеся, як трасування допомагає відстежувати запити між сервісами та знаходити затримки й помилки.

Що таке розподілене трасування

У монолітному застосунку запит зазвичай проходить через один процес. Щоб знайти проблему, достатньо переглянути його логи.

У розподіленій системі один користувацький запит може пройти через кілька сервісів:

text

Клієнт → API Gateway → Сервіс замовлень → Сервіс оплати → База даних

Кожен сервіс має власні логи та метрики. Без додаткового зв’язку складно визначити:

які саме сервіси обробляли запит;
де виникла помилка;
який сервіс додав найбільшу затримку;
чи пов’язана повільна відповідь із базою даних, мережею або конкретною операцією.

Розподілене трасування — це спосіб відстежити життєвий цикл одного запиту через усі сервіси, які його обробляють.

text

Trace: 4bf92f3577b34da6a3ce929d0e0e4736

├── API Gateway: 120 ms
├── Order Service: 85 ms
│   ├── PostgreSQL query: 30 ms
│   └── Payment Service: 45 ms
└── Response: 120 ms

text

GET /checkout — 850 ms
├── Load cart — 40 ms
├── Check inventory — 90 ms
├── Create payment — 680 ms
│   └── External payment API — 650 ms
└── Save order — 40 ms

text

Trace: abc123

├── API Gateway — OK
├── Order Service — OK
└── Payment Service — ERROR
    ├── status: ERROR
    ├── error.type: TimeoutError
    └── duration: 3000 ms

javascript

const http = require("node:http");
const crypto = require("node:crypto");

function randomHex(bytes) {
  return crypto.randomBytes(bytes).toString("hex");
}

function createTraceId() {
  return randomHex(16);
}

function createSpanId() {
  return randomHex(8);
}

function parseTraceparent(value) {
  if (typeof value !== "string") {
    return null;
  }

  const match = value.match(/^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i);

  if (!match) {
    return null;
  }

  return {
    traceId: match[1].toLowerCase(),
    parentSpanId: match[2].toLowerCase(),
    flags: match[3].toLowerCase()
  };
}

function makeTraceparent(traceId, spanId) {
  return `00-${traceId}-${spanId}-01`;
}

function logSpan(event, span) {
  console.log(JSON.stringify({
    event,
    service: span.service,
    operation: span.operation,
    trace_id: span.traceId,
    span_id: span.spanId,
    parent_span_id: span.parentSpanId || null,
    duration_ms: span.durationMs,
    status: span.status,
    error: span.error || null
  }));
}

function startSpan({ service, operation, traceId, parentSpanId }) {
  return {
    service,
    operation,
    traceId,
    spanId: createSpanId(),
    parentSpanId,
    startedAt: process.hrtime.bigint(),
    status: "OK",
    error: null
  };
}

function finishSpan(span, status = "OK", error = null) {
  const elapsed = process.hrtime.bigint() - span.startedAt;

  span.durationMs = Number(elapsed) / 1_000_000;
  span.status = status;
  span.error = error;

  logSpan("span.finished", span);
}

const orderService = http.createServer((req, res) => {
  const parent = parseTraceparent(req.headers.traceparent);

  const traceId = parent ? parent.traceId : createTraceId();

  const span = startSpan({
    service: "order-service",
    operation: `${req.method} ${req.url}`,
    traceId,
    parentSpanId: parent ? parent.parentSpanId : undefined
  });

  const shouldFail = new URL(req.url, "http://localhost").searchParams.get("fail") === "1";

  setTimeout(() => {
    if (shouldFail) {
      finishSpan(span, "ERROR", "Order storage is unavailable");

      res.writeHead(500, {
        "content-type": "application/json"
      });

      res.end(JSON.stringify({
        error: "order_service_failure",
        trace_id: traceId
      }));

      return;
    }

    finishSpan(span);

    res.writeHead(200, {
      "content-type": "application/json"
    });

    res.end(JSON.stringify({
      order_id: "order-123",
      trace_id: traceId
    }));
  }, 80);
});

const gateway = http.createServer((req, res) => {
  const incomingContext = parseTraceparent(req.headers.traceparent);

  const traceId = incomingContext
    ? incomingContext.traceId
    : createTraceId();

  const gatewaySpan = startSpan({
    service: "api-gateway",
    operation: `${req.method} ${req.url}`,
    traceId,
    parentSpanId: incomingContext
      ? incomingContext.parentSpanId
      : undefined
  });

  const orderServiceSpanId = createSpanId();

  const request = http.get(
    {
      hostname: "localhost",
      port: 3001,
      path: req.url,
      headers: {
        traceparent: makeTraceparent(traceId, orderServiceSpanId)
      }
    },
    (orderResponse) => {
      let body = "";

      orderResponse.setEncoding("utf8");

      orderResponse.on("data", (chunk) => {
        body += chunk;
      });

      orderResponse.on("end", () => {
        if (orderResponse.statusCode >= 500) {
          finishSpan(gatewaySpan, "ERROR", "Order Service returned an error");
        } else {
          finishSpan(gatewaySpan);
        }

        res.writeHead(orderResponse.statusCode, {
          "content-type": "application/json"
        });

        res.end(body);
      });
    }
  );

  request.on("error", (error) => {
    finishSpan(gatewaySpan, "ERROR", error.message);

    res.writeHead(502, {
      "content-type": "application/json"
    });

    res.end(JSON.stringify({
      error: "bad_gateway",
      trace_id: traceId
    }));
  });
});

orderService.listen(3001, () => {
  console.log("Order Service слухає http://localhost:3001");
});

gateway.listen(3000, () => {
  console.log("API Gateway слухає http://localhost:3000");
});

text

{"event":"span.finished","service":"order-service","operation":"GET /orders","trace_id":"...","span_id":"...","parent_span_id":"...","duration_ms":80.4,"status":"OK","error":null}
{"event":"span.finished","service":"api-gateway","operation":"GET /orders","trace_id":"...","span_id":"...","parent_span_id":null,"duration_ms":93.1,"status":"OK","error":null}