Invia dati

Instatus riceve log, trace e metriche con OpenTelemetry (OTLP su HTTPS). Ci sono due modi per collegare un’app. Scegline uno.

Opzione 1: Copia un prompt

Il modo più rapido, se usi un agente di programmazione come Claude Code, Cursor o Copilot.

  1. Apri Observability sulla tua pagina di stato.
  2. In Includi, spunta cosa vuoi inviare: Log, Trace, Metriche. Spunta anche Dashboard iniziale se in seguito vuoi dashboard pronte per i tuoi servizi.
  3. Fai clic su Copia prompt.
  4. Incollalo nel tuo agente di programmazione, nel progetto della tua app.
  5. Metti la tua chiave API nella variabile d’ambiente INSTATUS_API_KEY, poi esegui la prova suggerita dall’agente.
La scheda di configurazione, con log, trace e metriche da includere e un pulsante per copiare il prompt

Il prompt dice all’agente di usare l’SDK ufficiale di OpenTelemetry per il tuo linguaggio, mantenere la tua libreria di log attuale, leggere la chiave da una variabile d’ambiente e non fare mai il commit. L’ID della tua pagina è già incluso.

Opzione 2: Configura a mano

  1. Apri Observability sulla tua pagina di stato.
  2. Fai clic su Configura a mano.
  3. Scegli il tuo linguaggio: Node.js, Python, Go, Java, .NET, Ruby, PHP o l’OpenTelemetry Collector.
  4. Copia il comando Installa ed eseguilo, poi copia il codice Configura nella tua app.
  5. Imposta la variabile d’ambiente INSTATUS_API_KEY con la tua chiave API e avvia la tua app.
Configurazione a mano con Node.js selezionato, con il comando di installazione e il codice di configurazione

Il codice nella dashboard contiene già l’ID della tua pagina. Trovi gli stessi esempi qui sotto, se preferisci copiarli da qui.

Cosa serve a ogni richiesta

CosaValore
Endpointhttps://otel.instatus.com. I log vanno a /v1/logs, le trace a /v1/traces, le metriche a /v1/metrics.
AuthorizationBearer <API_KEY>, con la chiave di un proprietario, amministratore o editor della pagina.
X-Instatus-Site-IdL’ID della pagina di stato a cui appartengono i dati.
ProtocolloOTLP su HTTP, in protobuf o JSON. Se il tuo SDK usa gRPC per impostazione predefinita, passalo a HTTP.

La tua chiave API dà accesso a tutto il tuo account. Tienila sui tuoi server, in una variabile d’ambiente. Non metterla mai in un browser, in un’app mobile o in un repository pubblico.

Trova la tua chiave API

Apri il menu del tuo avatar, scegli Impostazioni utente, poi Sviluppatori, oppure vai direttamente alle impostazioni sviluppatore. Fai clic su Copia accanto alla chiave.

La chiave API nelle impostazioni sviluppatore, con un pulsante per copiarla

Trova l’ID della tua pagina

Serve di rado: il prompt e il codice nella dashboard lo contengono già. Per copiarlo da solo, fai clic destro sul nome del progetto in alto nella dashboard e scegli Copy Project ID.

Copy Project ID nel menu del nome del progetto

Invia un log di prova

Basta una richiesta da terminale per verificare la chiave e l’ID della pagina:

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 risposta 200 significa che il log è stato accettato. Apri Observability → Log e lo trovi lì in pochi secondi.

Qualsiasi linguaggio, senza modificare il codice

Ogni SDK di OpenTelemetry legge le stesse variabili d’ambiente. Con queste, l’auto-strumentazione invia trace, metriche e log senza toccare il tuo codice:

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"

Lo spazio dopo Bearer si scrive %20, perché la variabile degli header è codificata come URL. Poi avvia la tua app con l’auto-strumentazione del suo linguaggio:

# 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 hanno la propria auto-strumentazione e leggono le stesse variabili. Vedi le guide zero-code di OpenTelemetry.

Node.js

Per inviare log dal tuo codice, installa l’SDK dei log:

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

Configuralo una volta all’avvio della tua 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())

Usi già pino o winston? Tienili. pino-opentelemetry-transport e @opentelemetry/winston-transport inviano ogni riga di log così com’è.

Python

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

L’SDK si collega al modulo logging di Python, quindi le tue chiamate logging esistenti vengono inviate così come sono:

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

Usi già l’OpenTelemetry Collector? Aggiungi Instatus come exporter e lascia le tue app come sono:

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]

L’exporter aggiunge da solo /v1/logs, /v1/traces e /v1/metrics, quindi l’endpoint è solo l’host. Per inviare file di log, aggiungi un receiver filelog alla pipeline dei log.

Cosa inviare

Instatus legge questi campi. Tutto il resto viene conservato come attributo, su cui puoi cercare e filtrare.

CampoServe per
service.name (risorsa)La colonna e il filtro Servizio. Impostalo in ogni app, worker e job.
bodyIl messaggio del log, su cui lavora la ricerca a testo libero.
severityText o severityNumberIl livello: fatal, error, warn, info, debug o trace.
traceId e spanIdCollega un log alla sua trace, per passare dall’uno all’altra.
AttributiQualsiasi cosa aggiungi, come customer.id o http.route. Ognuno diventa un filtro.

Gli attributi che iniziano con instatus. sono riservati e vengono sostituiti all’arrivo dei dati.

Risoluzione dei problemi

VediSoluzione
401Controlla la chiave e l’header X-Instatus-Site-Id. Il titolare della chiave deve essere proprietario, amministratore o editor della pagina.
400Il body non è OTLP valido. Controlla Content-Type e la struttura JSON nel log di prova.
429Il volume di dati di questo mese è esaurito. Vedi piani e limiti.
200, ma non compare nullaAttendi qualche secondo, poi controlla l’intervallo di tempo. Un log con un timestamp nel passato compare solo se l’intervallo lo copre.
Proprio nienteGli SDK inviano a lotti. Assicurati che la tua app svuoti o chiuda il provider prima di terminare.

Rigenerare la chiave API nelle impostazioni sviluppatore disattiva subito quella vecchia, quindi aggiorna prima ogni app che la usa.