Enviar datos

Instatus recibe logs, trazas y métricas con OpenTelemetry (OTLP sobre HTTPS). Hay dos formas de conectar una app. Elige una.

Opción 1: Copia un prompt

La forma más rápida, si usas un agente de programación como Claude Code, Cursor o Copilot.

  1. Abre Observability en tu página de estado.
  2. En Incluir, marca lo que quieres enviar: Logs, Trazas, Métricas. Marca también Panel inicial si más adelante quieres paneles listos para tus servicios.
  3. Haz clic en Copiar prompt.
  4. Pégalo en tu agente de programación, dentro del proyecto de tu app.
  5. Guarda tu clave de API en la variable de entorno INSTATUS_API_KEY y ejecuta la prueba que sugiere el agente.
La tarjeta de configuración, con logs, trazas y métricas para incluir y un botón para copiar el prompt

El prompt le indica al agente que use el SDK oficial de OpenTelemetry para tu lenguaje, mantenga tu librería de logs actual, lea la clave de una variable de entorno y nunca la suba al repositorio. El ID de tu página ya está incluido.

Opción 2: Configura a mano

  1. Abre Observability en tu página de estado.
  2. Haz clic en Configurar a mano.
  3. Elige tu lenguaje: Node.js, Python, Go, Java, .NET, Ruby, PHP o el OpenTelemetry Collector.
  4. Copia el comando de Instalar y ejecútalo, luego copia el código de Configurar en tu app.
  5. Define la variable de entorno INSTATUS_API_KEY con tu clave de API e inicia tu app.
Configuración a mano con Node.js seleccionado, con el comando de instalación y el código de configuración

El código del panel ya lleva el ID de tu página. Tienes los mismos ejemplos abajo si prefieres copiarlos desde aquí.

Lo que necesita cada solicitud

QuéValor
Endpointhttps://otel.instatus.com. Los logs van a /v1/logs, las trazas a /v1/traces y las métricas a /v1/metrics.
AuthorizationBearer <API_KEY>, con la clave de un propietario, administrador o editor de la página.
X-Instatus-Site-IdEl ID de la página de estado a la que pertenecen los datos.
ProtocoloOTLP sobre HTTP, en protobuf o JSON. Si tu SDK usa gRPC por defecto, cámbialo a HTTP.

Tu clave de API da acceso a toda tu cuenta. Guárdala en tus servidores, en una variable de entorno. Nunca la pongas en un navegador, una app móvil o un repositorio público.

Encuentra tu clave de API

Abre el menú de tu avatar, elige Ajustes de usuario y luego Desarrollo, o ve directamente a la configuración de desarrollador. Haz clic en Copiar junto a la clave.

La clave de API en la configuración de desarrollador, con un botón para copiarla

Encuentra el ID de tu página

Casi nunca hace falta: el prompt y el código del panel ya lo contienen. Para copiarlo tú, haz clic derecho en el nombre del proyecto, arriba en el panel, y elige Copy Project ID.

Copy Project ID en el menú del nombre del proyecto

Envía un log de prueba

Basta una solicitud desde una terminal para comprobar tu clave y el ID de la 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" }
}]
}]
}]
}'

Una respuesta 200 significa que el log se aceptó. Abre Observability → Logs y estará ahí en pocos segundos.

Cualquier lenguaje, sin cambiar código

Todos los SDK de OpenTelemetry leen las mismas variables de entorno. Con ellas, la autoinstrumentación envía trazas, métricas y logs sin tocar tu 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"

El espacio después de Bearer se escribe %20, porque la variable de cabeceras va codificada como URL. Después inicia tu app con la autoinstrumentación de su lenguaje:

# 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 y PHP tienen su propia autoinstrumentación y leen las mismas variables. Consulta las guías sin código de OpenTelemetry.

Node.js

Para enviar logs desde tu código, instala el SDK de logs:

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

Configúralo una vez al iniciar tu 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())

¿Ya registras logs con pino o winston? Mantenlos. pino-opentelemetry-transport y @opentelemetry/winston-transport envían cada línea de log tal cual.

Python

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

El SDK se conecta al módulo logging de Python, así que tus llamadas actuales a logging se envían tal cual:

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

¿Ya usas el OpenTelemetry Collector? Añade Instatus como exportador y deja tus apps como están:

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]

El exportador añade /v1/logs, /v1/traces y /v1/metrics por su cuenta, así que el endpoint es solo el host. Para enviar archivos de log, añade un receptor filelog a la canalización de logs.

Qué enviar

Instatus lee estos campos. Todo lo demás se guarda como atributo por el que puedes buscar y filtrar.

CampoSe usa para
service.name (recurso)La columna y el filtro Servicio. Defínelo en cada app, worker y tarea.
bodyEl mensaje del log, en el que busca el texto libre.
severityText o severityNumberEl nivel: fatal, error, warn, info, debug o trace.
traceId y spanIdVincula un log a su traza, para saltar de uno a otra.
AtributosTodo lo que añadas, como customer.id o http.route. Cada uno se convierte en un filtro.

Los atributos que empiezan por instatus. están reservados y se sustituyen al llegar los datos.

Solución de problemas

VesSolución
401Revisa la clave y la cabecera X-Instatus-Site-Id. El dueño de la clave debe ser propietario, administrador o editor de la página.
400El cuerpo no es OTLP válido. Revisa Content-Type y la estructura JSON del log de prueba.
429Se agotó el volumen de datos de este mes. Consulta planes y límites.
200, pero no aparece nadaEspera unos segundos y revisa el rango de tiempo. Un log con una marca de tiempo pasada solo aparece si el rango la incluye.
Nada en absolutoLos SDK envían por lotes. Asegúrate de que tu app vacía o cierra el proveedor antes de terminar.

Al regenerar tu clave de API en la configuración de desarrollador, la anterior deja de funcionar al momento, así que actualiza antes cada app que la use.