# Wysyłanie danych

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

Instatus odbiera logi, ślady i metryki przez OpenTelemetry (OTLP po HTTPS). Aplikację można podłączyć na dwa sposoby. Wybierz jeden.

| At a glance | Details |
| :-- | :-- |
| [Najszybciej](https://instatus.com/help/pl/observability/send-logs#sposób-1-skopiuj-prompt) | Skopiuj prompt dla agenta programistycznego |
| [Ręcznie](https://instatus.com/help/pl/observability/send-logs#sposób-2-skonfiguruj-ręcznie) | Wybierz język i wklej kod |
| [Endpoint](https://instatus.com/help/pl/observability/send-logs#czego-potrzebuje-każde-żądanie) | https://otel.instatus.com i dwa nagłówki |
| [Test](https://instatus.com/help/pl/observability/send-logs#wyślij-testowy-log) | Jedno żądanie curl |
| [Nic się nie pojawia?](https://instatus.com/help/pl/observability/send-logs#rozwiązywanie-problemów) | Rozwiąż typowe problemy |

## Sposób 1: Skopiuj prompt

Najszybszy sposób, jeśli używasz agenta programistycznego, np. Claude Code, Cursor lub Copilot.

1. Otwórz **Observability** na swojej stronie statusu.
2. W sekcji **Uwzględnij** zaznacz, co chcesz wysyłać: **Logi**, **Ślady**, **Metryki**. Zaznacz też **Dashboard startowy**, jeśli później chcesz gotowe pulpity dla swoich usług.
3. Kliknij **Kopiuj prompt**.
4. Wklej go do agenta programistycznego, w projekcie swojej aplikacji.
5. Zapisz swój [klucz API](#znajdź-swój-klucz-api) w zmiennej środowiskowej `INSTATUS_API_KEY` i uruchom test zaproponowany przez agenta.

![Karta konfiguracji z logami, śladami i metrykami do wyboru oraz przyciskiem kopiowania promptu](https://instatus.com/help/observability/setup.png)

Prompt każe agentowi użyć oficjalnego SDK OpenTelemetry dla Twojego języka, zachować obecną bibliotekę logowania, czytać klucz ze zmiennej środowiskowej i nigdy go nie commitować. Identyfikator Twojej strony już w nim jest.

## Sposób 2: Skonfiguruj ręcznie

1. Otwórz **Observability** na swojej stronie statusu.
2. Kliknij **Skonfiguruj ręcznie**.
3. Wybierz język: Node.js, Python, Go, Java, .NET, Ruby, PHP lub OpenTelemetry Collector.
4. Skopiuj polecenie z sekcji **Instalacja** i uruchom je, a potem skopiuj kod z sekcji **Konfiguracja** do swojej aplikacji.
5. Ustaw zmienną środowiskową `INSTATUS_API_KEY` na swój [klucz API](#znajdź-swój-klucz-api) i uruchom aplikację.

![Ręczna konfiguracja z wybranym Node.js, z poleceniem instalacji i kodem konfiguracji](https://instatus.com/help/observability/setup-by-hand.png)

Kod w panelu ma już wpisany identyfikator Twojej strony. Te same przykłady znajdziesz niżej, jeśli wolisz skopiować je stąd.

## Czego potrzebuje każde żądanie

| Co          | Wartość                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Endpoint      | `https://otel.instatus.com`. Logi trafiają do `/v1/logs`, ślady do `/v1/traces`, metryki do `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, z kluczem właściciela, administratora lub edytora strony.                    |
| `X-Instatus-Site-Id` | Identyfikator strony statusu, do której należą dane.                                                |
| Protokół      | OTLP po HTTP, jako protobuf lub JSON. Jeśli Twoje SDK domyślnie używa gRPC, przełącz je na HTTP.          |

> Twój klucz API daje dostęp do całego konta. Trzymaj go na swoich serwerach, w zmiennej środowiskowej. Nigdy nie umieszczaj go w przeglądarce, aplikacji mobilnej ani publicznym repozytorium.

### Znajdź swój klucz API

Otwórz menu pod awatarem, wybierz **Ustawienia użytkownika**, a potem **Deweloper**, albo przejdź od razu do [ustawień dewelopera](https://dashboard.instatus.com/developer). Kliknij **Kopiuj** obok klucza.

![Klucz API w ustawieniach dewelopera, z przyciskiem kopiowania](https://instatus.com/help/observability/api-key.png)

### Znajdź identyfikator strony

Rzadko jest potrzebny: prompt i kod w panelu już go zawierają. Aby skopiować go samodzielnie, kliknij prawym przyciskiem nazwę projektu na górze panelu i wybierz **Copy Project ID**.

![Copy Project ID w menu nazwy projektu](https://instatus.com/help/observability/copy-page-id.png)

## Wyślij testowy log

Jedno żądanie z terminala wystarczy, by sprawdzić klucz i identyfikator strony:

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

Odpowiedź `200` oznacza, że log został przyjęty. Otwórz **Observability** → **Logi**, a pojawi się w ciągu kilku sekund.

## Dowolny język, bez zmian w kodzie

Każde SDK OpenTelemetry czyta te same zmienne środowiskowe. Dzięki nim automatyczna instrumentacja wysyła ślady, metryki i logi bez dotykania kodu:

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

Spację po `Bearer` zapisuje się jako `%20`, bo zmienna nagłówków jest kodowana jak URL. Następnie uruchom aplikację z automatyczną instrumentacją dla jej języka:

```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 i PHP mają własną automatyczną instrumentację i czytają te same zmienne. Zobacz [przewodniki zero-code OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

Aby wysyłać logi z kodu, zainstaluj SDK logów:

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

Skonfiguruj je raz przy starcie aplikacji:

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

Logujesz już przez **pino** lub **winston**? Zostaw je. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) i [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) wysyłają każdą istniejącą linię logu bez zmian.

## Python

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

SDK podpina się pod moduł `logging` Pythona, więc Twoje obecne wywołania `logging` są wysyłane bez zmian:

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

Masz już OpenTelemetry Collector? Dodaj Instatus jako eksporter i zostaw aplikacje bez zmian:

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

Eksporter sam dopisuje `/v1/logs`, `/v1/traces` i `/v1/metrics`, więc endpoint to tylko host. Aby wysyłać pliki logów, dodaj odbiornik `filelog` do potoku logów.

## Co wysyłać

Instatus czyta te pola. Wszystko inne zostaje zapisane jako atrybut, po którym można wyszukiwać i filtrować.

| Pole                       | Do czego służy                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (zasób)      | Kolumna i filtr **Usługa**. Ustaw go w każdej aplikacji, workerze i zadaniu. |
| `body`                             | Treść logu, którą przeszukuje wyszukiwanie tekstowe.                                                     |
| `severityText` lub `severityNumber` | Poziom: `fatal`, `error`, `warn`, `info`, `debug` lub `trace`.                                  |
| `traceId` i `spanId`             | Łączy log z jego śladem, by można było przechodzić między nimi.                                          |
| Atrybuty                     | Wszystko, co dodasz, np. `customer.id` lub `http.route`. Każdy staje się filtrem.               |

Atrybuty zaczynające się od `instatus.` są zarezerwowane i zastępowane po odebraniu danych.

## Rozwiązywanie problemów

| Widzisz               | Rozwiązanie                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Sprawdź klucz i nagłówek `X-Instatus-Site-Id`. Właściciel klucza musi być właścicielem, administratorem lub edytorem strony.       |
| `400`                       | Treść żądania nie jest poprawnym OTLP. Sprawdź `Content-Type` i strukturę JSON w [testowym logu](#wyślij-testowy-log).             |
| `429`                       | Limit danych na ten miesiąc został wykorzystany. Zobacz [plany i limity](https://instatus.com/help/pl/observability#plany-i-limity).                    |
| `200`, ale nic się nie pojawia | Poczekaj kilka sekund, a potem sprawdź zakres czasu. Log ze znacznikiem czasu z przeszłości pojawi się tylko, gdy zakres go obejmuje. |
| Zupełnie nic              | SDK wysyłają dane partiami. Upewnij się, że aplikacja opróżnia lub zamyka dostawcę przed zakończeniem.                           |

Wygenerowanie nowego klucza API w ustawieniach dewelopera od razu unieważnia stary, więc najpierw zaktualizuj każdą aplikację, która go używa.

- [Logi](https://instatus.com/help/pl/observability/logs): Przeszukuj, filtruj i śledź logi na żywo
- [Ślady](https://instatus.com/help/pl/observability/traces): Zobacz, na co każde żądanie traci czas
