# Отправка данных

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

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

| At a glance | Details |
| :-- | :-- |
| [Быстрее всего](https://instatus.com/help/ru/observability/send-logs#способ-1-скопируйте-промпт) | Скопируйте промпт для агента |
| [Вручную](https://instatus.com/help/ru/observability/send-logs#способ-2-настройте-вручную) | Выберите язык и вставьте код |
| [Эндпоинт](https://instatus.com/help/ru/observability/send-logs#что-нужно-каждому-запросу) | https://otel.instatus.com и два заголовка |
| [Проверка](https://instatus.com/help/ru/observability/send-logs#отправьте-тестовый-лог) | Один запрос curl |
| [Ничего не видно?](https://instatus.com/help/ru/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/ru/observability#тарифы-и-лимиты).                    |
| `200`, но ничего не появляется | Подождите несколько секунд и проверьте период. Лог с меткой времени в прошлом появится, только если период её охватывает. |
| Совсем ничего              | SDK отправляют данные пачками. Убедитесь, что приложение сбрасывает или закрывает провайдер перед завершением.                           |

После перевыпуска API-ключа в настройках разработчика старый ключ сразу перестаёт работать, поэтому сначала обновите все приложения, которые его используют.

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