OpenTelemetry

Status200 neemt logs, metrics en traces op via het OpenTelemetry Protocol (OTLP). Richt een willekeurige OpenTelemetry-SDK, of een OpenTelemetry Collector, met een ingestiesleutel op Status200, en je gegevens verschijnen onder Logboeken, Traces, Metrieken en Uitzonderingen. Deze pagina laat een service binnen een paar minuten gegevens sturen en behandelt daarna de endpoints, limieten en fouten die je in productie nodig hebt.

Hoe het werkt#

Je applicatie exporteert OTLP rechtstreeks naar Status200, of naar een OpenTelemetry Collector die het doorstuurt. Elk verzoek draagt je ingestiesleutel in de header x-status200-token, en Status200 gebruikt de sleutel om je project te vinden.

• Services worden voor je aangemaakt. Het resource-attribuut service.name (ingesteld met OTEL_SERVICE_NAME) geeft de service een naam waartoe je gegevens horen. Status200 maakt de service aan zodra die voor het eerst stuurt, en toont hem onder Producten → Services.
• Fouten worden uitzonderingen. Uitzonderingsgebeurtenissen op spans, en uitzonderingen die in logs zijn vastgelegd, worden onder Uitzonderingen gegroepeerd in issues — zie Uitzonderingen uit logs.
• Regels werken op gegevens zodra ze binnenkomen. Drop-filters en scrub-regels gooien weg of maskeren wat je nooit wilt opslaan, en gegevensbewaring bepaalt hoe lang de rest wordt bewaard.

Voordat je begint#

• Een Status200-project waarin je ingestiesleutels mag maken: projecteigenaren en -beheerders mogen dat, en ook iedereen met de machtiging Create Telemetry Ingestion Key.
• Een applicatie waaraan je een OpenTelemetry-SDK kunt toevoegen, of een OpenTelemetry Collector.
• Uitgaand HTTPS (poort 443) van je applicatie of collector naar status200.ru, of naar je eigen Status200-host.

Snelstart#

1. Een ingestiesleutel maken#

   1. Ga naar Producten → Projectinstellingen.
   2. Open in het zijmenu Telemetrie & APM en kies Ingestiesleutels.
   3. Klik op Inname-sleutel aanmaken. Het dialoogvenster vult een naam in en kiest het sleuteltype Server, waarmee een applicatie of een collector stuurt. Geef hem eventueel een andere naam en klik dan op Inname-sleutel aanmaken.

   

   De nieuwe sleutel opent op een eigen pagina. Kopieer de Geheime sleutel — dat is het token dat je als x-status200-token stuurt.

   

2. De OpenTelemetry-omgevingsvariabelen instellen#

   Elke OpenTelemetry-SDK leest dezelfde standaard omgevingsvariabelen, dus deze stap is in elke taal hetzelfde.

   Omgevingsvariabele	Waarde	Wat het doet
   OTEL_EXPORTER_OTLP_ENDPOINT	https://status200.ru/otlp	Waarheen te sturen. De SDK voegt zelf /v1/traces, /v1/metrics en /v1/logs toe.
   OTEL_EXPORTER_OTLP_HEADERS	x-status200-token=YOUR_STATUS200_INGESTION_KEY	Stuurt je ingestiesleutel mee met elk verzoek.
   OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	OTLP via HTTP. Sommige SDK's gebruiken standaard gRPC, dat een ander endpoint gebruikt.
   OTEL_SERVICE_NAME	my-service	De service waaronder je gegevens in Status200 verschijnen.

   Bash

   export OTEL_EXPORTER_OTLP_ENDPOINT="https://status200.ru/otlp"
   export OTEL_EXPORTER_OTLP_HEADERS="x-status200-token=YOUR_STATUS200_INGESTION_KEY"
   export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
   export OTEL_SERVICE_NAME="my-service"

   Zelf gehost? Vervang https://status200.ru door de URL van je Status200-instantie, bijvoorbeeld https://status200.example.com/otlp. Om uitzonderingen met een omgeving te labelen, stel je ook OTEL_RESOURCE_ATTRIBUTES in op deployment.environment=production.

3. OpenTelemetry aan je app toevoegen#

   Kies je taal. Elke opzet leest de omgevingsvariabelen hierboven, dus er staat geen endpoint of sleutel in je code.

   Node.jsPythonGoJava.NET

   Node.js

   Installeer de SDK, de automatische instrumentaties en de OTLP/HTTP-exporters:

   Bash

   npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
     @opentelemetry/exporter-trace-otlp-proto @opentelemetry/exporter-metrics-otlp-proto \
     @opentelemetry/exporter-logs-otlp-proto @opentelemetry/sdk-metrics @opentelemetry/sdk-logs

   Maak de SDK in een eigen bestand:

   instrumentation.jsJavaScript

   const { NodeSDK } = require("@opentelemetry/sdk-node");
   const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
   const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-proto");
   const { OTLPMetricExporter } = require("@opentelemetry/exporter-metrics-otlp-proto");
   const { OTLPLogExporter } = require("@opentelemetry/exporter-logs-otlp-proto");
   const { PeriodicExportingMetricReader } = require("@opentelemetry/sdk-metrics");
   const { BatchLogRecordProcessor } = require("@opentelemetry/sdk-logs");
   
   // The exporters read OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS.
   const sdk = new NodeSDK({
     traceExporter: new OTLPTraceExporter(),
     metricReader: new PeriodicExportingMetricReader({
       exporter: new OTLPMetricExporter(),
     }),
     logRecordProcessors: [new BatchLogRecordProcessor(new OTLPLogExporter())],
     instrumentations: [getNodeAutoInstrumentations()],
   });
   
   sdk.start();

   Laad het vóór je applicatiecode:

   Bash

   node --require ./instrumentation.js app.js

   Python

   Installeer de OpenTelemetry-distributie en de exporter, en daarna de instrumentaties voor de bibliotheken die je app gebruikt:

   Bash

   pip install opentelemetry-distro opentelemetry-exporter-otlp
   opentelemetry-bootstrap -a install

   Start je app via opentelemetry-instrument. Het exporteert traces, metrics en logs; de logging-variabele stuurt ook records die met de logging-module van Python zijn geschreven:

   Bash

   OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py

   Go

   Voeg de SDK en de OTLP/HTTP-exporters toe:

   Bash

   go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/sdk/metric \
     go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
     go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp

   Maak de tracer- en meter-providers wanneer je programma start:

   main.goGo

   package main
   
   import (
       "context"
       "log"
   
       "go.opentelemetry.io/otel"
       "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
       "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
       sdkmetric "go.opentelemetry.io/otel/sdk/metric"
       sdktrace "go.opentelemetry.io/otel/sdk/trace"
   )
   
   func main() {
       ctx := context.Background()
   
       // Both exporters read OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS.
       traceExporter, err := otlptracehttp.New(ctx)
       if err != nil {
           log.Fatal(err)
       }
       tracerProvider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(traceExporter))
       defer tracerProvider.Shutdown(ctx)
       otel.SetTracerProvider(tracerProvider)
   
       metricExporter, err := otlpmetrichttp.New(ctx)
       if err != nil {
           log.Fatal(err)
       }
       meterProvider := sdkmetric.NewMeterProvider(
           sdkmetric.WithReader(sdkmetric.NewPeriodicReader(metricExporter)),
       )
       defer meterProvider.Shutdown(ctx)
       otel.SetMeterProvider(meterProvider)
   
       // Your application code.
   }

   De providers halen OTEL_SERVICE_NAME uit de omgeving. Voeg voor logs otlploghttp toe met een log-bridge zoals otelslog; die leest dezelfde variabelen.

   Java

   Download de OpenTelemetry Java-agent en koppel hem aan je applicatie. Er zijn geen codewijzigingen nodig:

   Bash

   curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
   java -javaagent:opentelemetry-javaagent.jar -jar my-app.jar

   De agent instrumenteert gangbare frameworks en bibliotheken, en exporteert traces, metrics en logs die via Logback of Log4j worden geschreven.

   .NET

   Voeg de OpenTelemetry-pakketten voor ASP.NET Core toe:

   Bash

   dotnet add package OpenTelemetry.Extensions.Hosting
   dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
   dotnet add package OpenTelemetry.Instrumentation.AspNetCore
   dotnet add package OpenTelemetry.Instrumentation.Http

   Registreer OpenTelemetry bij het opstarten. UseOtlpExporter() stuurt traces, metrics en logs, en leest de variabelen OTEL_EXPORTER_OTLP_*:

   Program.csC#

   using OpenTelemetry;
   using OpenTelemetry.Metrics;
   using OpenTelemetry.Trace;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddOpenTelemetry()
       .WithTracing(tracing => tracing
           .AddAspNetCoreInstrumentation()
           .AddHttpClientInstrumentation())
       .WithMetrics(metrics => metrics
           .AddAspNetCoreInstrumentation()
           .AddHttpClientInstrumentation())
       .WithLogging()
       .UseOtlpExporter();
   
   var app = builder.Build();
   app.Run();

   Gebruik je Serilog? Zie Serilog om de logs ervan naar Status200 te sturen.

4. Controleren of gegevens binnenkomen#

   Vraag Status200 of het je sleutel accepteert:

   Bash

   curl -i -H "x-status200-token: YOUR_STATUS200_INGESTION_KEY" \
     https://status200.ru/otlp/v1/validate

   Een werkende sleutel geeft 200 met "valid": true. Al het andere geeft 401 met een melding wat er mis is — onbekend, uitgeschakeld of verlopen.

   Start daarna je app en gebruik hem een minuut. Open Producten → Services: je service staat daar onder de naam die je in OTEL_SERVICE_NAME hebt ingesteld, met zijn logs, traces, metrics en uitzonderingen. Producten → Logboeken, Producten → Traces en Producten → Metrieken tonen dezelfde gegevens voor alle services.

curl -i https://status200.ru/otlp/v1/logs \
  -H "Content-Type: application/json" \
  -H "x-status200-token: YOUR_STATUS200_INGESTION_KEY" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "my-service" } }
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "severityNumber": 9,
          "body": { "stringValue": "Hello from curl" }
        }]
      }]
    }]
  }'

Via een OpenTelemetry Collector sturen#

Draai een collector als je er al een hebt, als je gegevens op één plek wilt bundelen, filteren of verrijken, of om de ingestiesleutel buiten je applicaties te houden. Je apps exporteren naar de collector, en alleen de collector praat met Status200.

1. Status200 als exporter toevoegen#

   Voeg een otlphttp-exporter toe die naar Status200 wijst, en stuur elke pipeline erdoorheen:

   otel-collector-config.yamlYAML

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   
   processors:
     batch: {}
   
   exporters:
     otlphttp:
       endpoint: https://status200.ru/otlp
       headers:
         x-status200-token: YOUR_STATUS200_INGESTION_KEY
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlphttp]
       metrics:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlphttp]
       logs:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlphttp]

   Houd de standaardinstellingen van de exporter aan: hij stuurt protobuf, gecomprimeerd met gzip, en Status200 accepteert beide. Stel geen Content-Type-header in op de exporter — Status200 kiest zijn decoder op basis van die header, dus een JSON-contenttype vóór protobuf-bytes breekt de ingestie.

2. De collector starten#

   DockerLinux

   Docker

   Bash

   docker run -d --name otel-collector \
     -p 4317:4317 -p 4318:4318 \
     -v "$(pwd)/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml" \
     otel/opentelemetry-collector-contrib:latest

   Linux

   Bash

   otelcol-contrib --config otel-collector-config.yaml

   De collector luistert naar OTLP op poort 4317 (gRPC) en 4318 (HTTP), de poorten waar SDK's standaard naartoe sturen.

3. Je apps op de collector richten#

   Stel in je applicaties OTEL_EXPORTER_OTLP_ENDPOINT in op de collector, bijvoorbeeld http://localhost:4318, en verwijder OTEL_EXPORTER_OTLP_HEADERS — de collector voegt de sleutel toe. Behoud OTEL_SERVICE_NAME in elke applicatie.

   Gegevens komen in Status200 precies zo binnen als in de snelstart. Zo niet, dan staat in het log van de collector waarom — zie Problemen oplossen.

Exporteer je al naar een andere leverancier? Voeg de otlphttp-exporter toe naast de bestaande en noem beide in de exporters van elke pipeline, zodat je tijdens het vergelijken naar allebei stuurt. Om ook hostmetrics en logbestanden te verzamelen, zie de handleiding Host OpenTelemetry Collector.

Endpoints en limieten#

Via HTTP heeft elk signaal een eigen pad onder het endpoint. SDK's en de collector voegen het voor je toe; stel het alleen zelf in als een tool om een volledige URL vraagt.

Voor continue profilering sturen de meeste profilers naar het Pyroscope-compatibele endpoint — zie Continue profilering. Een collector die OTLP-profielen exporteert, moet het profiles_endpoint van de exporter instellen op https://status200.ru/otlp/v1/profiles, omdat hij profielen standaard naar een ontwikkelpad stuurt dat Status200 niet bedient.

OTLP via gRPC#

Status200 biedt OTLP/gRPC aan op dezelfde host als de webapp, op poort 443 via TLS. Stel OTEL_EXPORTER_OTLP_PROTOCOL in op grpc en OTEL_EXPORTER_OTLP_ENDPOINT op https://status200.ru:443, en stuur dezelfde header x-status200-token. Gebruik in een collector de exporter otlp met endpoint: status200.ru:443 en dezelfde headers.

Bij een zelf gehoste installatie bereikt gRPC Status200 alleen via HTTPS: een onversleutelde HTTP-verbinding (h2c) wordt geweigerd. Wordt je instantie via gewoon HTTP aangeboden, gebruik dan OTLP/HTTP.

Twee instellingen van een sleutel gelden alleen voor OTLP/HTTP: de Requests Per Minute Limit en de Pinned Service Name. Via gRPC verstuurde gegevens houden de service.name waarmee ze zijn verstuurd, en tellen niet mee voor de limiet.

Antwoorden#

Status200 beantwoordt een export zodra de gegevens in de wachtrij staan, en de gegevens verschijnen een paar seconden later.

401, 402, 413, 415 en 422 zijn permanente fouten voor OTLP-exporters: de exporter laat de batch vallen en logt de fout in plaats van het opnieuw te proberen.

Herstarts en upgrades#

Terwijl Status200 herstart of wordt geüpgraded, beantwoordt het exports met 503 en Retry-After: 5 tot het klaar is, en exporters sturen ze opnieuw. De exporter van een collector blijft standaard vijf minuten opnieuw proberen (retry_on_failure) en bewaart wat hij niet kon versturen in zijn sending_queue, dus laat beide ingeschakeld. De tijd waarin Status200 niets ontving, wordt je servers, hosts en andere resources nooit aangerekend: zie Wanneer Status200 geen gegevens ontvangt.

Ingestiesleutels#

De pagina van elke sleutel, onder Projectinstellingen → Telemetrie & APM → Ingestiesleutels, heeft deze instellingen:

Geheime sleutel opnieuw instellen op de pagina van de sleutel vervangt het geheim. Elke applicatie en collector die met het oude stuurt, wordt geweigerd tot je hem bijwerkt. Voor browsersleutels, het veilig vervangen van een sleutel en wat elke weigering betekent, zie Ingestiesleutels.

Zelf gehoste Status200#

Alles op deze pagina werkt op dezelfde manier met je eigen installatie. Gebruik je Status200-URL overal waar deze pagina https://status200.ru zegt:

• OTEL_EXPORTER_OTLP_ENDPOINT is https://YOUR-ONEUPTIME-HOST/otlp, of http://YOUR-ONEUPTIME-HOST/otlp als je Status200 via gewoon HTTP aanbiedt.
• De meegeleverde ingress accepteert verzoeken tot 4 MB op /otlp. Een proxy die je vóór Status200 draait, kan een lagere limiet hebben — ingress-nginx stelt proxy-body-size standaard in op 1 MB —, dus verhoog die ook voor /otlp, anders krijgen exporters 413.
• Als DISABLE_TELEMETRY_INGESTION=true is ingesteld, accepteert Status200 elke export en slaat het niets op. Controleer dit eerst als een zelf gehoste instantie helemaal geen gegevens toont.

Uitzonderingen uit logs#

Status200 vindt uitzonderingen in je logs en brengt ze samen in dezelfde weergave Uitzonderingen die door tracefouten wordt gevoed. Elk log hoort al bij een service of host, dus de uitzondering wordt daaraan toegewezen. Uitzonderingen uit logs en traces delen de groepering op vingerafdruk, zodat een fout die zowel door een trace als door een log wordt gemeld, samenvalt tot één issue.

Er zijn twee manieren waarop een log een uitzondering wordt:

Het doorzoeken van de body past bij platte-tekstlogs zoals ruwe stdout, journald of syslog die een collector leest. Een stacktrace van meerdere regels moet als één logrecord aankomen, dus schakel het samenvoegen van meerdere regels in de collector in — zie de handleiding Host OpenTelemetry Collector.

Detectie staat standaard aan. Bij een zelf gehoste installatie zet je hem uit door TELEMETRY_LOG_EXCEPTION_EXTRACTION_ENABLED=false in te stellen op de service app — en ook op de worker als je de aparte worker van de Helm-chart draait.

Problemen oplossen#

Volgende stappen#