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

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

Способ 1: скопируйте промпт

Самый быстрый путь, если вы пользуетесь агентом для программирования, например Claude Code, Cursor или Copilot.

  1. Откройте Observability на странице статуса.
  2. В блоке Включить отметьте, что хотите отправлять: Логи, Трейсы, Метрики. Отметьте и Стартовый дашборд, если позже вам понадобятся готовые дашборды для ваших сервисов.
  3. Нажмите Скопировать промпт.
  4. Вставьте его в агент, открыв проект своего приложения.
  5. Сохраните API-ключ в переменной окружения INSTATUS_API_KEY и запустите проверку, которую предложит агент.
Карточка настройки с выбором логов, трейсов и метрик и кнопкой копирования промпта

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

Способ 2: настройте вручную

  1. Откройте Observability на странице статуса.
  2. Нажмите Настроить вручную.
  3. Выберите язык: Node.js, Python, Go, Java, .NET, Ruby, PHP или OpenTelemetry Collector.
  4. Скопируйте команду из блока Установка и выполните её, затем скопируйте код из блока Настройка в приложение.
  5. Укажите API-ключ в переменной окружения INSTATUS_API_KEY и запустите приложение.
Ручная настройка с выбранным Node.js: команда установки и код конфигурации

В коде на дашборде ID вашей страницы уже подставлен. Те же примеры есть ниже, если удобнее копировать отсюда.

Что нужно каждому запросу

ЧтоЗначение
Эндпоинтhttps://otel.instatus.com. Логи отправляются на /v1/logs, трейсы — на /v1/traces, метрики — на /v1/metrics.
AuthorizationBearer <API_KEY> с ключом владельца, администратора или редактора страницы.
X-Instatus-Site-IdID страницы статуса, к которой относятся данные.
ПротоколOTLP поверх HTTP, в формате protobuf или JSON. Если ваш SDK по умолчанию использует gRPC, переключите его на HTTP.

API-ключ даёт доступ ко всей вашей учётной записи. Храните его на своих серверах, в переменной окружения. Никогда не размещайте его в браузере, мобильном приложении или публичном репозитории.

Где найти API-ключ

Откройте меню аватара, выберите Настройки пользователя, затем Разработчику, или сразу перейдите в настройки разработчика. Нажмите Копировать рядом с ключом.

API-ключ в настройках разработчика с кнопкой копирования

Где найти ID страницы

Обычно он не нужен: промпт и код на дашборде уже его содержат. Чтобы скопировать его самостоятельно, щёлкните правой кнопкой мыши по названию проекта вверху дашборда и выберите Copy Project ID.

Copy Project ID в меню названия проекта

Отправьте тестовый лог

Чтобы проверить ключ и ID страницы, достаточно одного запроса из терминала:

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 читают одни и те же переменные окружения. С ними автоинструментирование отправляет трейсы, метрики и логи, не затрагивая ваш код:

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. Затем запустите приложение с автоинструментированием для его языка:

# 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 без кода.

Node.js

Чтобы отправлять логи из кода, установите SDK для логов:

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

Настройте его один раз при запуске приложения:

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 и @opentelemetry/winston-transport отправляют каждую существующую строку лога как есть.

Python

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

SDK подключается к модулю logging в Python, поэтому существующие вызовы logging отправляются как есть:

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 как экспортёр, а приложения оставьте как есть:

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Объём данных за этот месяц исчерпан. См. тарифы и лимиты.
200, но ничего не появляетсяПодождите несколько секунд и проверьте период. Лог с меткой времени в прошлом появится, только если период её охватывает.
Совсем ничегоSDK отправляют данные пачками. Убедитесь, что приложение сбрасывает или закрывает провайдер перед завершением.

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