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

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-ключа в налаштуваннях розробника старий ключ одразу перестає працювати, тож спершу оновіть усі застосунки, які його використовують.