# Data versturen

Source: https://instatus.com/help/nl/observability/send-logs

Instatus ontvangt logs, traces en metrics via OpenTelemetry (OTLP over HTTPS). Er zijn twee manieren om een app te koppelen. Kies er één.

| At a glance | Details |
| :-- | :-- |
| [Snelst](https://instatus.com/help/nl/observability/send-logs#optie-1-kopieer-een-prompt) | Een prompt voor je codeeragent kopiëren |
| [Handmatig](https://instatus.com/help/nl/observability/send-logs#optie-2-handmatig-instellen) | Kies je taal en plak de code |
| [Endpoint](https://instatus.com/help/nl/observability/send-logs#wat-elk-verzoek-nodig-heeft) | https://otel.instatus.com, plus twee headers |
| [Test](https://instatus.com/help/nl/observability/send-logs#een-testlog-sturen) | Eén curl-verzoek |
| [Zie je niets?](https://instatus.com/help/nl/observability/send-logs#problemen-oplossen) | Los de meest voorkomende problemen op |

## Optie 1: Kopieer een prompt

De snelste manier, als je een codeeragent gebruikt zoals Claude Code, Cursor of Copilot.

1. Open **Observability** op je statuspagina.
2. Vink onder **Meenemen** aan wat je wilt sturen: **Logs**, **Traces**, **Metrics**. Vink ook **Startdashboard** aan als je later kant-en-klare dashboards voor je services wilt.
3. Klik op **Prompt kopiëren**.
4. Plak de prompt in je codeeragent, in het project van je app.
5. Zet je [API-sleutel](#je-api-sleutel-vinden) in de omgevingsvariabele `INSTATUS_API_KEY` en voer de test uit die de agent voorstelt.

![De instelkaart met logs, traces en metrics om mee te sturen en een knop om de prompt te kopiëren](https://instatus.com/help/observability/setup.png)

De prompt vraagt de agent de officiële OpenTelemetry-SDK voor je taal te gebruiken, je huidige logbibliotheek te houden, de sleutel uit een omgevingsvariabele te lezen en die nooit te committen. Je pagina-ID staat er al in.

## Optie 2: Handmatig instellen

1. Open **Observability** op je statuspagina.
2. Klik op **Handmatig instellen**.
3. Kies je taal: Node.js, Python, Go, Java, .NET, Ruby, PHP of de OpenTelemetry Collector.
4. Kopieer de opdracht onder **Installeren** en voer die uit, en kopieer daarna de code onder **Configureren** in je app.
5. Zet de omgevingsvariabele `INSTATUS_API_KEY` op je [API-sleutel](#je-api-sleutel-vinden) en start je app.

![Handmatig instellen met Node.js geselecteerd, met de installatieopdracht en de configuratiecode](https://instatus.com/help/observability/setup-by-hand.png)

In de code in het dashboard staat je pagina-ID al ingevuld. Dezelfde voorbeelden vind je hieronder als je liever hier kopieert.

## Wat elk verzoek nodig heeft

| Wat          | Waarde                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Endpoint      | `https://otel.instatus.com`. Logs gaan naar `/v1/logs`, traces naar `/v1/traces`, metrics naar `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, met de sleutel van een eigenaar, beheerder of editor van de pagina.                    |
| `X-Instatus-Site-Id` | De ID van de statuspagina waar de data bij hoort.                                                |
| Protocol      | OTLP over HTTP, als protobuf of JSON. Gebruikt je SDK standaard gRPC, zet het dan om naar HTTP.          |

> Je API-sleutel geeft toegang tot je hele account. Bewaar hem op je servers, in een omgevingsvariabele. Zet hem nooit in een browser, een mobiele app of een openbare repository.

### Je API-sleutel vinden

Open het menu onder je avatar, kies **Gebruikersinstellingen** en dan **Ontwikkelaar**, of ga direct naar de [ontwikkelaarsinstellingen](https://dashboard.instatus.com/developer). Klik naast de sleutel op **Kopiëren**.

![De API-sleutel in de ontwikkelaarsinstellingen, met een knop om hem te kopiëren](https://instatus.com/help/observability/api-key.png)

### Je pagina-ID vinden

Dat is zelden nodig: de prompt en de code in het dashboard bevatten hem al. Wil je hem zelf kopiëren, klik dan met de rechtermuisknop op de projectnaam bovenaan het dashboard en kies **Copy Project ID**.

![Copy Project ID in het menu van de projectnaam](https://instatus.com/help/observability/copy-page-id.png)

## Een testlog sturen

Eén verzoek vanuit een terminal is genoeg om je sleutel en pagina-ID te controleren:

```bash
curl -X POST https://otel.instatus.com/v1/logs \
  -H "Authorization: Bearer $INSTATUS_API_KEY" \
  -H "X-Instatus-Site-Id: $INSTATUS_PAGE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "api" } }
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s)'000000000",
          "severityText": "INFO",
          "body": { "stringValue": "Hello from Instatus" }
        }]
      }]
    }]
  }'
```

Een `200`-antwoord betekent dat de log is geaccepteerd. Open **Observability** → **Logs** en hij staat er binnen een paar seconden.

## Elke taal, zonder codewijzigingen

Elke OpenTelemetry-SDK leest dezelfde omgevingsvariabelen. Daarmee stuurt auto-instrumentatie traces, metrics en logs zonder dat je je code aanraakt:

```bash
export OTEL_SERVICE_NAME="api"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.instatus.com"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${INSTATUS_API_KEY},X-Instatus-Site-Id=${INSTATUS_PAGE_ID}"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
```

De spatie na `Bearer` schrijf je als `%20`, omdat de header-variabele URL-gecodeerd is. Start je app daarna met de auto-instrumentatie voor zijn taal:

```bash
# Node.js
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register app.js

# Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py
```

Java, .NET, Go, Ruby en PHP hebben hun eigen auto-instrumentatie en lezen dezelfde variabelen. Zie de [zero-code-handleidingen van OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

Om logs vanuit je code te sturen, installeer je de logs-SDK:

```bash
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \
  @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
```

Stel hem één keer in bij het starten van je app:

```js
import { SeverityNumber } from '@opentelemetry/api-logs'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs'

const provider = new LoggerProvider({
  resource: resourceFromAttributes({ 'service.name': 'api' }),
  processors: [
    new BatchLogRecordProcessor(
      new OTLPLogExporter({
        url: 'https://otel.instatus.com/v1/logs',
        headers: {
          Authorization: `Bearer ${process.env.INSTATUS_API_KEY}`,
          'X-Instatus-Site-Id': process.env.INSTATUS_PAGE_ID
        }
      })
    )
  ]
})

const logger = provider.getLogger('api')

logger.emit({
  severityNumber: SeverityNumber.ERROR,
  severityText: 'ERROR',
  body: 'Payment failed: card declined',
  attributes: { 'customer.id': 'cus_123', route: '/v2/charges' }
})

process.on('beforeExit', () => provider.shutdown())
```

Log je al met **pino** of **winston**? Houd ze. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) en [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) sturen elke bestaande logregel ongewijzigd.

## Python

```bash
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

De SDK haakt in op de `logging`-module van Python, dus je bestaande `logging`-aanroepen worden ongewijzigd verstuurd:

```python
import logging
import os

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.resources import Resource

provider = LoggerProvider(resource=Resource.create({"service.name": "worker"}))
provider.add_log_record_processor(
    BatchLogRecordProcessor(
        OTLPLogExporter(
            endpoint="https://otel.instatus.com/v1/logs",
            headers={
                "Authorization": f"Bearer {os.environ['INSTATUS_API_KEY']}",
                "X-Instatus-Site-Id": os.environ["INSTATUS_PAGE_ID"],
            },
        )
    )
)
set_logger_provider(provider)

logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=provider))
logging.getLogger().setLevel(logging.INFO)

logging.warning("Card declined for customer %s", "cus_123")
```

## OpenTelemetry Collector

Draai je al de OpenTelemetry Collector? Voeg Instatus toe als exporter en laat je apps zoals ze zijn:

```yaml
exporters:
  otlphttp/instatus:
    endpoint: https://otel.instatus.com
    headers:
      Authorization: Bearer ${env:INSTATUS_API_KEY}
      X-Instatus-Site-Id: ${env:INSTATUS_PAGE_ID}

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
```

De exporter voegt `/v1/logs`, `/v1/traces` en `/v1/metrics` zelf toe, dus het endpoint is alleen de host. Om logbestanden te sturen, voeg je een `filelog`-receiver toe aan de logs-pipeline.

## Wat je stuurt

Instatus leest deze velden. Al het andere blijft bewaard als kenmerk waarop je kunt zoeken en filteren.

| Veld                       | Gebruikt voor                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (resource)      | De kolom en het filter **Service**. Stel het in in elke app, worker en taak. |
| `body`                             | Het logbericht, waarin vrije tekst zoekt.                                                     |
| `severityText` of `severityNumber` | Het niveau: `fatal`, `error`, `warn`, `info`, `debug` of `trace`.                                  |
| `traceId` en `spanId`             | Koppelt een log aan zijn trace, zodat je tussen beide kunt springen.                                          |
| Kenmerken                     | Alles wat je toevoegt, zoals `customer.id` of `http.route`. Elk wordt een filter.               |

Kenmerken die met `instatus.` beginnen zijn gereserveerd en worden vervangen bij binnenkomst.

## Problemen oplossen

| Je ziet               | Oplossing                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Controleer de sleutel en de header `X-Instatus-Site-Id`. De eigenaar van de sleutel moet eigenaar, beheerder of editor van de pagina zijn.       |
| `400`                       | De body is geen geldige OTLP. Controleer `Content-Type` en de JSON-structuur in de [testlog](#een-testlog-sturen).             |
| `429`                       | Het datavolume van deze maand is op. Zie [abonnementen en limieten](https://instatus.com/help/nl/observability#abonnementen-en-limieten).                    |
| `200`, maar er verschijnt niets | Wacht een paar seconden en controleer dan de periode. Een log met een tijdstempel in het verleden verschijnt alleen als de periode die dekt. |
| Helemaal niets              | SDK’s sturen in batches. Zorg dat je app de provider leegt of afsluit voordat hij stopt.                           |

Een nieuwe API-sleutel maken in de ontwikkelaarsinstellingen stopt de oude meteen. Werk dus eerst elke app bij die hem gebruikt.

- [Logs](https://instatus.com/help/nl/observability/logs): Je logs doorzoeken, filteren en live volgen
- [Traces](https://instatus.com/help/nl/observability/traces): Zien waar elk verzoek zijn tijd aan besteedt
