# Надсилання даних

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

Instatus приймає логи, трейси й метрики через OpenTelemetry (OTLP поверх HTTPS). Підключити застосунок можна двома способами. Оберіть один.

| At a glance | Details |
| :-- | :-- |
| [Найшвидше](https://instatus.com/help/uk/observability/send-logs#спосіб-1-скопіюйте-промпт) | Скопіюйте промпт для агента |
| [Вручну](https://instatus.com/help/uk/observability/send-logs#спосіб-2-налаштуйте-вручну) | Оберіть мову й вставте код |
| [Ендпоінт](https://instatus.com/help/uk/observability/send-logs#що-потрібно-кожному-запиту) | https://otel.instatus.com і два заголовки |
| [Перевірка](https://instatus.com/help/uk/observability/send-logs#надішліть-тестовий-лог) | Один запит curl |
| [Нічого не видно?](https://instatus.com/help/uk/observability/send-logs#розвязання-проблем) | Розв’яжіть типові проблеми |

## Спосіб 1: скопіюйте промпт

Найшвидший шлях, якщо ви користуєтеся агентом для програмування, наприклад Claude Code, Cursor чи Copilot.

1. Відкрийте **Observability** на сторінці статусу.
2. У блоці **Включити** позначте, що хочете надсилати: **Логи**, **Трейси**, **Метрики**. Позначте й **Стартовий дашборд**, якщо згодом вам знадобляться готові дашборди для ваших сервісів.
3. Натисніть **Скопіювати промпт**.
4. Вставте його в агента, відкривши проєкт свого застосунку.
5. Збережіть [API-ключ](#де-знайти-api-ключ) у змінній середовища `INSTATUS_API_KEY` і запустіть перевірку, яку запропонує агент.

![Картка налаштування з вибором логів, трейсів і метрик та кнопкою копіювання промпту](https://instatus.com/help/observability/setup.png)

Промпт просить агента використати офіційний SDK OpenTelemetry для вашої мови, зберегти поточну бібліотеку логування, читати ключ зі змінної середовища й ніколи його не комітити. ID вашої сторінки в ньому вже є.

## Спосіб 2: налаштуйте вручну

1. Відкрийте **Observability** на сторінці статусу.
2. Натисніть **Налаштувати вручну**.
3. Оберіть мову: Node.js, Python, Go, Java, .NET, Ruby, PHP або OpenTelemetry Collector.
4. Скопіюйте команду з блоку **Встановлення** і виконайте її, потім скопіюйте код із блоку **Налаштування** у застосунок.
5. Вкажіть [API-ключ](#де-знайти-api-ключ) у змінній середовища `INSTATUS_API_KEY` і запустіть застосунок.

![Ручне налаштування з вибраним Node.js: команда встановлення й код конфігурації](https://instatus.com/help/observability/setup-by-hand.png)

У коді на дашборді ID вашої сторінки вже підставлено. Ті самі приклади є нижче, якщо зручніше копіювати звідси.

## Що потрібно кожному запиту

| Що          | Значення                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Ендпоінт      | `https://otel.instatus.com`. Логи надсилаються на `/v1/logs`, трейси — на `/v1/traces`, метрики — на `/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>` із ключем власника, адміністратора чи редактора сторінки.                    |
| `X-Instatus-Site-Id` | ID сторінки статусу, до якої належать дані.                                                |
| Протокол      | OTLP поверх HTTP, у форматі protobuf або JSON. Якщо ваш SDK типово використовує gRPC, перемкніть його на HTTP.          |

> API-ключ дає доступ до всього вашого облікового запису. Зберігайте його на своїх серверах, у змінній середовища. Ніколи не розміщуйте його в браузері, мобільному застосунку чи публічному репозиторії.

### Де знайти API-ключ

Відкрийте меню аватара, оберіть **Налаштування користувача**, потім **Розробнику**, або одразу перейдіть до [налаштувань розробника](https://dashboard.instatus.com/developer). Натисніть **Копіювати** поруч із ключем.

![API-ключ у налаштуваннях розробника з кнопкою копіювання](https://instatus.com/help/observability/api-key.png)

### Де знайти ID сторінки

Зазвичай він не потрібен: промпт і код на дашборді вже його містять. Щоб скопіювати його самостійно, клацніть правою кнопкою миші назву проєкту вгорі дашборда й оберіть **Copy Project ID**.

![Copy Project ID у меню назви проєкту](https://instatus.com/help/observability/copy-page-id.png)

## Надішліть тестовий лог

Щоб перевірити ключ і ID сторінки, достатньо одного запиту з термінала:

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

Відповідь `200` означає, що лог прийнято. Відкрийте **Observability** → **Логи**, і за кілька секунд він з’явиться.

## Будь-яка мова, без змін у коді

Усі SDK OpenTelemetry читають ті самі змінні середовища. З ними автоінструментування надсилає трейси, метрики й логи, не торкаючись вашого коду:

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

Пробіл після `Bearer` записується як `%20`, бо змінна заголовків кодується як URL. Потім запустіть застосунок з автоінструментуванням для його мови:

```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 і PHP мають власне автоінструментування, яке читає ті самі змінні. Див. [посібники OpenTelemetry без коду](https://opentelemetry.io/docs/zero-code/).

## Node.js

Щоб надсилати логи з коду, встановіть SDK для логів:

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

Налаштуйте його один раз під час запуску застосунку:

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

Уже логуєте через **pino** чи **winston**? Залиште їх. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) і [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) надсилають кожен наявний рядок логу як є.

## Python

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

SDK підключається до модуля `logging` у Python, тож наявні виклики `logging` надсилаються як є:

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

Уже використовуєте OpenTelemetry Collector? Додайте Instatus як експортер, а застосунки залиште як є:

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

Експортер сам додає `/v1/logs`, `/v1/traces` і `/v1/metrics`, тож в ендпоінті вказується лише хост. Щоб надсилати файли логів, додайте ресивер `filelog` у пайплайн логів.

## Що надсилати

Instatus читає ці поля. Усе інше зберігається як атрибут, за яким можна шукати й фільтрувати.

| Поле                       | Для чого                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (ресурс)      | Стовпець і фільтр **Сервіс**. Задайте його в кожному застосунку, воркері й задачі. |
| `body`                             | Текст логу, за яким іде повнотекстовий пошук.                                                     |
| `severityText` або `severityNumber` | Рівень: `fatal`, `error`, `warn`, `info`, `debug` або `trace`.                                  |
| `traceId` і `spanId`             | Пов’язує лог із його трейсом, щоб переходити між ними.                                          |
| Атрибути                     | Усе, що ви додасте, наприклад `customer.id` або `http.route`. Кожен атрибут стає фільтром.               |

Атрибути, що починаються з `instatus.`, зарезервовані й замінюються під час надходження даних.

## Розв’язання проблем

| Що видно               | Що робити                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | Перевірте ключ і заголовок `X-Instatus-Site-Id`. Власник ключа має бути власником, адміністратором чи редактором сторінки.       |
| `400`                       | Тіло запиту не є коректним OTLP. Перевірте `Content-Type` і структуру JSON у [тестовому лозі](#надішліть-тестовий-лог).             |
| `429`                       | Обсяг даних за цей місяць вичерпано. Див. [тарифи й обмеження](https://instatus.com/help/uk/observability#тарифи-й-обмеження).                    |
| `200`, але нічого не з’являється | Зачекайте кілька секунд і перевірте період. Лог із міткою часу в минулому з’явиться, лише якщо період її охоплює. |
| Зовсім нічого              | SDK надсилають дані пакетами. Переконайтеся, що застосунок скидає або закриває провайдер перед завершенням.                           |

Після перевипуску API-ключа в налаштуваннях розробника старий ключ одразу перестає працювати, тож спершу оновіть усі застосунки, які його використовують.

- [Логи](https://instatus.com/help/uk/observability/logs): Шукайте, фільтруйте й переглядайте логи наживо
- [Трейси](https://instatus.com/help/uk/observability/traces): Дивіться, на що кожен запит витрачає час
