# Daten senden

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

Instatus empfängt Logs, Traces und Metriken über OpenTelemetry (OTLP über HTTPS). Es gibt zwei Wege, eine App zu verbinden. Wählen Sie einen.

| At a glance | Details |
| :-- | :-- |
| [Am schnellsten](https://instatus.com/help/de/observability/send-logs#weg-1-einen-prompt-kopieren) | Einen Prompt für Ihren Coding-Agenten kopieren |
| [Von Hand](https://instatus.com/help/de/observability/send-logs#weg-2-von-hand-einrichten) | Sprache wählen und Code einfügen |
| [Endpunkt](https://instatus.com/help/de/observability/send-logs#was-jede-anfrage-braucht) | https://otel.instatus.com, plus zwei Header |
| [Test](https://instatus.com/help/de/observability/send-logs#ein-test-log-senden) | Eine curl-Anfrage |
| [Nichts zu sehen?](https://instatus.com/help/de/observability/send-logs#fehlerbehebung) | Die häufigsten Probleme beheben |

## Weg 1: Einen Prompt kopieren

Der schnellste Weg, wenn Sie einen Coding-Agenten wie Claude Code, Cursor oder Copilot nutzen.

1. Öffnen Sie **Observability** auf Ihrer Statusseite.
2. Wählen Sie unter **Einbeziehen**, was Sie senden möchten: **Logs**, **Traces**, **Metriken**. Wählen Sie auch **Start-Dashboard**, wenn Sie später fertige Dashboards für Ihre Dienste möchten.
3. Klicken Sie auf **Prompt kopieren**.
4. Fügen Sie ihn in Ihren Coding-Agenten ein, im Projekt Ihrer App.
5. Legen Sie Ihren [API-Schlüssel](#ihren-api-schlüssel-finden) in der Umgebungsvariable `INSTATUS_API_KEY` ab und führen Sie den Test aus, den der Agent vorschlägt.

![Die Einrichtungskarte mit Logs, Traces und Metriken zur Auswahl und einer Schaltfläche zum Kopieren des Prompts](https://instatus.com/help/observability/setup.png)

Der Prompt sagt dem Agenten, das offizielle OpenTelemetry-SDK Ihrer Sprache zu nutzen, Ihre bestehende Logging-Bibliothek zu behalten, den Schlüssel aus einer Umgebungsvariable zu lesen und ihn nie zu committen. Ihre Seiten-ID steht schon darin.

## Weg 2: Von Hand einrichten

1. Öffnen Sie **Observability** auf Ihrer Statusseite.
2. Klicken Sie auf **Manuell einrichten**.
3. Wählen Sie Ihre Sprache: Node.js, Python, Go, Java, .NET, Ruby, PHP oder den OpenTelemetry Collector.
4. Kopieren Sie den Befehl unter **Installieren** und führen Sie ihn aus, dann kopieren Sie den Code unter **Konfigurieren** in Ihre App.
5. Setzen Sie die Umgebungsvariable `INSTATUS_API_KEY` auf Ihren [API-Schlüssel](#ihren-api-schlüssel-finden) und starten Sie Ihre App.

![Von Hand einrichten mit ausgewähltem Node.js, mit dem Installationsbefehl und dem Konfigurationscode](https://instatus.com/help/observability/setup-by-hand.png)

Im Code im Dashboard ist Ihre Seiten-ID bereits eingetragen. Dieselben Beispiele finden Sie unten, falls Sie lieber hier kopieren.

## Was jede Anfrage braucht

| Was          | Wert                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Endpunkt      | `https://otel.instatus.com`. Logs gehen an `/v1/logs`, Traces an `/v1/traces`, Metriken an `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, mit dem Schlüssel eines Eigentümers, Admins oder Editors der Seite.                    |
| `X-Instatus-Site-Id` | Die ID der Statusseite, zu der die Daten gehören.                                                |
| Protokoll      | OTLP über HTTP, als Protobuf oder JSON. Nutzt Ihr SDK standardmäßig gRPC, stellen Sie es auf HTTP um.          |

> Ihr API-Schlüssel gibt Zugriff auf Ihr gesamtes Konto. Bewahren Sie ihn auf Ihren Servern auf, in einer Umgebungsvariable. Legen Sie ihn nie in einen Browser, eine mobile App oder ein öffentliches Repository.

### Ihren API-Schlüssel finden

Öffnen Sie Ihr Avatar-Menü, wählen Sie **Benutzereinstellungen** und dann **Entwickler**, oder gehen Sie direkt zu den [Entwicklereinstellungen](https://dashboard.instatus.com/developer). Klicken Sie neben dem Schlüssel auf **Kopieren**.

![Der API-Schlüssel in den Entwicklereinstellungen mit einer Schaltfläche zum Kopieren](https://instatus.com/help/observability/api-key.png)

### Ihre Seiten-ID finden

Das ist selten nötig: Der Prompt und der Code im Dashboard enthalten sie schon. Um sie selbst zu kopieren, klicken Sie mit der rechten Maustaste auf den Projektnamen oben im Dashboard und wählen **Copy Project ID**.

![Copy Project ID im Menü des Projektnamens](https://instatus.com/help/observability/copy-page-id.png)

## Ein Test-Log senden

Eine Anfrage aus dem Terminal genügt, um Schlüssel und Seiten-ID zu prüfen:

```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" }
        }]
      }]
    }]
  }'
```

Eine `200`-Antwort heißt, das Log wurde angenommen. Öffnen Sie **Observability** → **Logs**, und es ist innerhalb weniger Sekunden da.

## Jede Sprache, ohne Codeänderungen

Jedes OpenTelemetry-SDK liest dieselben Umgebungsvariablen. Damit sendet die Auto-Instrumentierung Traces, Metriken und Logs, ohne dass Sie Ihren Code anfassen:

```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"
```

Das Leerzeichen nach `Bearer` wird als `%20` geschrieben, weil die Header-Variable URL-kodiert ist. Starten Sie Ihre App dann mit der Auto-Instrumentierung ihrer Sprache:

```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 und PHP haben eigene Auto-Instrumentierung und lesen dieselben Variablen. Siehe die [Zero-Code-Anleitungen von OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

Um Logs aus Ihrem Code zu senden, installieren Sie das Logs-SDK:

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

Richten Sie es einmal beim Start Ihrer App ein:

```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())
```

Sie loggen schon mit **pino** oder **winston**? Behalten Sie sie. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) und [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) senden jede bestehende Logzeile unverändert.

## Python

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

Das SDK hängt sich in Pythons `logging`-Modul ein, Ihre bestehenden `logging`-Aufrufe werden also unverändert gesendet:

```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

Sie betreiben schon den OpenTelemetry Collector? Fügen Sie Instatus als Exporter hinzu und lassen Sie Ihre Apps, wie sie sind:

```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]
```

Der Exporter hängt `/v1/logs`, `/v1/traces` und `/v1/metrics` selbst an, der Endpunkt ist also nur der Host. Um Logdateien zu senden, fügen Sie der Logs-Pipeline einen `filelog`-Receiver hinzu.

## Was Sie senden

Instatus liest diese Felder. Alles andere bleibt als Attribut erhalten, nach dem Sie suchen und filtern können.

| Feld                       | Wofür                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (Ressource)      | Die Spalte und der Filter **Dienst**. Setzen Sie es in jeder App, jedem Worker und jedem Job. |
| `body`                             | Die Lognachricht, die die Freitextsuche durchsucht.                                                     |
| `severityText` oder `severityNumber` | Die Stufe: `fatal`, `error`, `warn`, `info`, `debug` oder `trace`.                                  |
| `traceId` und `spanId`             | Verknüpft ein Log mit seinem Trace, damit Sie zwischen beiden springen können.                                          |
| Attribute                     | Alles, was Sie ergänzen, etwa `customer.id` oder `http.route`. Jedes wird zu einem Filter.               |

Attribute, die mit `instatus.` beginnen, sind reserviert und werden beim Eingang ersetzt.

## Fehlerbehebung

| Sie sehen               | Lösung                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Prüfen Sie den Schlüssel und den Header `X-Instatus-Site-Id`. Der Besitzer des Schlüssels muss Eigentümer, Admin oder Editor der Seite sein.       |
| `400`                       | Der Body ist kein gültiges OTLP. Prüfen Sie `Content-Type` und die JSON-Struktur im [Test-Log](#ein-test-log-senden).             |
| `429`                       | Das Datenvolumen dieses Monats ist aufgebraucht. Siehe [Tarife und Limits](https://instatus.com/help/de/observability#tarife-und-limits).                    |
| `200`, aber nichts erscheint | Warten Sie ein paar Sekunden und prüfen Sie dann den Zeitraum. Ein Log mit einem Zeitstempel in der Vergangenheit erscheint nur, wenn der Zeitraum ihn abdeckt. |
| Gar nichts              | SDKs senden in Stapeln. Stellen Sie sicher, dass Ihre App den Provider leert oder herunterfährt, bevor sie sich beendet.                           |

Wenn Sie Ihren API-Schlüssel in den Entwicklereinstellungen neu erzeugen, funktioniert der alte sofort nicht mehr. Aktualisieren Sie also vorher jede App, die ihn nutzt.

- [Logs](https://instatus.com/help/de/observability/logs): Logs durchsuchen, filtern und live verfolgen
- [Traces](https://instatus.com/help/de/observability/traces): Sehen, wo jede Anfrage ihre Zeit verbringt
