Φόρτωση περιεχομένου...
Φόρτωση περιεχομένου...
Μάθετε να ενεργοποιείτε tracing με registerOTel, να στέλνετε spans σε collector και να συνδέετε traces με logs.
Όταν ένα request περνά από middleware, Server Component, query βάσης και εξωτερικό API, κανένα log από μόνο του δεν σας λέει πού πήγε ο χρόνος. Το trace ενώνει όλα τα βήματα (spans) κάτω από ένα ID — και το Next.js 16 το υποστηρίζει εγγενώς μέσω instrumentation.ts.
Αυτό το μάθημα προϋποθέτει βασικό Next.js (App Router, Server Components) — ξεκινήστε από το Welcome to Next.js 16.
Η επίσημη τεκμηρίωση του Next.js (φάκελος node_modules/next/dist/docs, σελίδες instrumentation και instrumentation guide) συνιστά το πακέτο @vercel/otel (έκδοση 2.1.3 από το npm registry, επαληθευμένη 2026-10-26). Το αρχείο μπαίνει στη ρίζα του project (ή φάκελο src), ποτέ μέσα στο app:
npm install @vercel/otelimport { registerOTel } from '@vercel/otel';
export function register() {
registerOTel('next-app');
}Η συνάρτηση register καλείται μία φορά όταν ξεκινά ο server, πριν δεχτεί requests. Το όρισμα ('next-app') είναι το όνομα υπηρεσίας που θα βλέπετε στα traces.
Χωρίς collector, τα spans δεν έχουν πού να πάνε. Η @vercel/otel διαβάζει τις κλασικές μεταβλητές περιβάλλοντος του OpenTelemetry:
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1Στην παραγωγή δεν στέλνετε το 100% των traces — το κόστος αποθήκευσης εκρήγνυται. Δειγματοληψία 10% (όπως παραπάνω) αρκεί για τάσεις, και για κρίσιμα μονοπάτια (checkout, πληρωμές) κρατάτε πάντα δείγμα με head-based κανόνα στο collector.
Σηκώστε έναν collector που ακούει OTLP/HTTP στη θύρα 4318 και τυπώνει τα spans στα logs του:
# docker-compose.yml — προσθήκη
services:
otel-collector:
image: otel/opentelemetry-collector-contrib:0.165.0
command: ['--config=/etc/otel/config.yaml']
volumes:
- ./otel-collector-config.yaml:/etc/otel/config.yaml:ro
ports: ['127.0.0.1:4318:4318']
restart: unless-stopped# otel-collector-config.yaml
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
exporters:
debug:
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
exporters: [debug]Επαληθεύστε ότι φτάνουν spans: φορτώστε μία σελίδα της εφαρμογής και δείτε τα traces στα logs του collector:
docker compose up -d otel-collector
docker compose logs --follow otel-collectorΤο προαιρετικό onRequestError (σταθερό από Next 15, σύμφωνα με τα version history docs) στέλνει τα server errors στον παρατηρητή σας:
import type { Instrumentation } from 'next';
export const onRequestError: Instrumentation.onRequestError = async (err, request, context) => {
const message = err instanceof Error ? err.message : String(err);
await fetch('https://example.com/report-error', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message, path: request.path, route: context.routePath }),
});
};Και η γέφυρα με τα logs: γράψτε το trace ID σε κάθε γραμμή (το reqId του μαθήματος pino γίνεται το trace ID), ώστε από ένα αργό span να πηδάτε στις ακριβείς γραμμές log — και αντίστροφα.
docker compose logs.instrumentation.ts στη ρίζα (ή src/) με registerOTel('όνομα-υπηρεσίας') — η επίσημη οδός των Next.js docs.onRequestError για server errors· κοινό trace ID σε spans και logs για αμφίδρομη πλοήγηση.