Enviar dados

O Instatus recebe logs, traces e métricas via OpenTelemetry (OTLP sobre HTTPS). Há duas formas de conectar um app. Escolha uma.

Opção 1: Copie um prompt

O jeito mais rápido, se você usa um agente de programação como Claude Code, Cursor ou Copilot.

  1. Abra Observability na sua página de status.
  2. Em Incluir, marque o que deseja enviar: Logs, Traces, Métricas. Marque também Dashboard inicial se quiser dashboards prontos para seus serviços depois.
  3. Clique em Copiar prompt.
  4. Cole no seu agente de programação, no projeto do seu app.
  5. Coloque sua chave de API na variável de ambiente INSTATUS_API_KEY e rode o teste sugerido pelo agente.
O cartão de configuração, com logs, traces e métricas para incluir e um botão para copiar o prompt

O prompt instrui o agente a usar o SDK oficial do OpenTelemetry para sua linguagem, manter sua biblioteca de logs atual, ler a chave de uma variável de ambiente e nunca fazer commit dela. O ID da sua página já está nele.

Opção 2: Configure manualmente

  1. Abra Observability na sua página de status.
  2. Clique em Configurar manualmente.
  3. Escolha sua linguagem: Node.js, Python, Go, Java, .NET, Ruby, PHP ou o OpenTelemetry Collector.
  4. Copie o comando de Instalar e rode, depois copie o código de Configurar para o seu app.
  5. Defina a variável de ambiente INSTATUS_API_KEY com sua chave de API e inicie seu app.
Configuração manual com Node.js selecionado, mostrando o comando de instalação e o código de configuração

O código no painel já vem com o ID da sua página preenchido. Os mesmos exemplos estão abaixo, se preferir copiar daqui.

O que toda requisição precisa

O quêValor
Endpointhttps://otel.instatus.com. Logs vão para /v1/logs, traces para /v1/traces e métricas para /v1/metrics.
AuthorizationBearer <API_KEY>, com a chave de um proprietário, admin ou editor da página.
X-Instatus-Site-IdO ID da página de status a que os dados pertencem.
ProtocoloOTLP sobre HTTP, em protobuf ou JSON. Se o seu SDK usa gRPC por padrão, mude para HTTP.

Sua chave de API dá acesso à sua conta inteira. Guarde-a nos seus servidores, em uma variável de ambiente. Nunca a coloque em um navegador, um app móvel ou um repositório público.

Encontre sua chave de API

Abra o menu do seu avatar, escolha Configurações do usuário e depois Desenvolvedor, ou vá direto para as configurações de desenvolvedor. Clique em Copiar ao lado da chave.

A chave de API nas configurações de desenvolvedor, com um botão para copiá-la

Encontre o ID da sua página

Raramente é necessário: o prompt e o código no painel já o contêm. Para copiá-lo você mesmo, clique com o botão direito no nome do projeto no topo do painel e escolha Copy Project ID.

Copy Project ID no menu do nome do projeto

Envie um log de teste

Uma requisição de um terminal basta para verificar sua chave e o ID da página:

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

Uma resposta 200 significa que o log foi aceito. Abra Observability → Logs e ele aparece em poucos segundos.

Qualquer linguagem, sem mudar o código

Todo SDK do OpenTelemetry lê as mesmas variáveis de ambiente. Com elas, a autoinstrumentação envia traces, métricas e logs sem mexer no seu código:

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"

O espaço depois de Bearer é escrito como %20, porque a variável de cabeçalhos é codificada como URL. Depois inicie seu app com a autoinstrumentação da linguagem dele:

# 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 e PHP têm autoinstrumentação própria e leem as mesmas variáveis. Veja os guias zero-code do OpenTelemetry.

Node.js

Para enviar logs a partir do código, instale o SDK de logs:

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

Configure-o uma vez ao iniciar o app:

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

Já registra logs com pino ou winston? Mantenha-os. pino-opentelemetry-transport e @opentelemetry/winston-transport enviam cada linha de log como ela é.

Python

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

O SDK se conecta ao módulo logging do Python, então suas chamadas de logging existentes são enviadas como são:

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

Já roda o OpenTelemetry Collector? Adicione o Instatus como exportador e deixe seus apps como estão:

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]

O exportador adiciona /v1/logs, /v1/traces e /v1/metrics sozinho, então o endpoint é só o host. Para enviar arquivos de log, adicione um receptor filelog ao pipeline de logs.

O que enviar

O Instatus lê estes campos. Todo o resto é mantido como atributo, que você pode pesquisar e filtrar.

CampoUsado para
service.name (recurso)A coluna e o filtro Serviço. Defina em cada app, worker e job.
bodyA mensagem do log, onde a busca por texto procura.
severityText ou severityNumberO nível: fatal, error, warn, info, debug ou trace.
traceId e spanIdLiga um log ao seu trace, para você ir de um ao outro.
AtributosTudo o que você adicionar, como customer.id ou http.route. Cada um vira um filtro.

Atributos que começam com instatus. são reservados e substituídos quando os dados chegam.

Solução de problemas

Você vêSolução
401Verifique a chave e o cabeçalho X-Instatus-Site-Id. O dono da chave precisa ser proprietário, admin ou editor da página.
400O corpo não é um OTLP válido. Verifique o Content-Type e a estrutura JSON do log de teste.
429A franquia de dados deste mês acabou. Veja planos e limites.
200, mas nada apareceEspere alguns segundos e confira o período. Um log com data no passado só aparece se o período a incluir.
Absolutamente nadaOs SDKs enviam em lotes. Garanta que seu app esvazie ou encerre o provider antes de sair.

Gerar uma nova chave de API nas configurações de desenvolvedor desativa a antiga na hora, então atualize antes cada app que a usa.