Envoyer des données

Instatus reçoit les logs, traces et métriques via OpenTelemetry (OTLP sur HTTPS). Il y a deux façons de connecter une app. Choisissez-en une.

Option 1 : Copier un prompt

La méthode la plus rapide, si vous utilisez un agent de code comme Claude Code, Cursor ou Copilot.

  1. Ouvrez Observability sur votre page de statut.
  2. Sous Inclure, cochez ce que vous voulez envoyer : Logs, Traces, Métriques. Cochez aussi Tableau de bord de départ si vous voulez plus tard des tableaux de bord prêts à l’emploi pour vos services.
  3. Cliquez sur Copier le prompt.
  4. Collez-le dans votre agent de code, dans le projet de votre app.
  5. Placez votre clé d’API dans la variable d’environnement INSTATUS_API_KEY, puis lancez le test proposé par l’agent.
La carte de configuration, avec les logs, traces et métriques à inclure et un bouton pour copier le prompt

Le prompt demande à l’agent d’utiliser le SDK OpenTelemetry officiel de votre langage, de garder votre bibliothèque de logs actuelle, de lire la clé dans une variable d’environnement et de ne jamais la committer. L’ID de votre page y figure déjà.

Option 2 : Configurer à la main

  1. Ouvrez Observability sur votre page de statut.
  2. Cliquez sur Configurer manuellement.
  3. Choisissez votre langage : Node.js, Python, Go, Java, .NET, Ruby, PHP ou l’OpenTelemetry Collector.
  4. Copiez la commande Installer et exécutez-la, puis copiez le code Configurer dans votre app.
  5. Définissez la variable d’environnement INSTATUS_API_KEY avec votre clé d’API et lancez votre app.
Configuration à la main avec Node.js sélectionné, montrant la commande d’installation et le code de configuration

Le code du tableau de bord contient déjà l’ID de votre page. Les mêmes exemples figurent ci-dessous si vous préférez les copier ici.

Ce dont chaque requête a besoin

QuoiValeur
Endpointhttps://otel.instatus.com. Les logs vont vers /v1/logs, les traces vers /v1/traces, les métriques vers /v1/metrics.
AuthorizationBearer <API_KEY>, avec la clé d’un propriétaire, administrateur ou éditeur de la page.
X-Instatus-Site-IdL’ID de la page de statut à laquelle appartiennent les données.
ProtocoleOTLP sur HTTP, en protobuf ou JSON. Si votre SDK utilise gRPC par défaut, passez-le en HTTP.

Votre clé d’API donne accès à tout votre compte. Gardez-la sur vos serveurs, dans une variable d’environnement. Ne la mettez jamais dans un navigateur, une app mobile ou un dépôt public.

Trouver votre clé d’API

Ouvrez le menu de votre avatar, choisissez Paramètres du compte, puis Développeur, ou allez directement dans les paramètres développeur. Cliquez sur Copier à côté de la clé.

La clé d’API dans les paramètres développeur, avec un bouton pour la copier

Trouver l’ID de votre page

C’est rarement nécessaire : le prompt et le code du tableau de bord le contiennent déjà. Pour le copier vous-même, faites un clic droit sur le nom du projet en haut du tableau de bord et choisissez Copy Project ID.

Copy Project ID dans le menu du nom du projet

Envoyer un log de test

Une seule requête depuis un terminal suffit pour vérifier votre clé et l’ID de la page :

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

Une réponse 200 signifie que le log a été accepté. Ouvrez Observability → Logs : il est là en quelques secondes.

Tous les langages, sans modifier le code

Tous les SDK OpenTelemetry lisent les mêmes variables d’environnement. Avec elles, l’auto-instrumentation envoie traces, métriques et logs sans toucher à votre code :

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"

L’espace après Bearer s’écrit %20, car la variable des en-têtes est encodée comme une URL. Lancez ensuite votre app avec l’auto-instrumentation de son langage :

# 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 et PHP ont leur propre auto-instrumentation et lisent les mêmes variables. Voir les guides sans code d’OpenTelemetry.

Node.js

Pour envoyer des logs depuis votre code, installez le SDK de logs :

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

Configurez-le une fois au démarrage de votre 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())

Vous utilisez déjà pino ou winston ? Gardez-les. pino-opentelemetry-transport et @opentelemetry/winston-transport envoient chaque ligne de log telle quelle.

Python

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

Le SDK se branche sur le module logging de Python, vos appels logging existants sont donc envoyés tels quels :

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

Vous utilisez déjà l’OpenTelemetry Collector ? Ajoutez Instatus comme exportateur et laissez vos apps telles quelles :

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’exportateur ajoute lui-même /v1/logs, /v1/traces et /v1/metrics, l’endpoint est donc juste l’hôte. Pour envoyer des fichiers de log, ajoutez un récepteur filelog au pipeline de logs.

Quoi envoyer

Instatus lit ces champs. Tout le reste est conservé comme attribut, que vous pouvez rechercher et filtrer.

ChampSert à
service.name (ressource)La colonne et le filtre Service. Définissez-le dans chaque app, worker et tâche.
bodyLe message du log, sur lequel porte la recherche en texte libre.
severityText ou severityNumberLe niveau : fatal, error, warn, info, debug ou trace.
traceId et spanIdRelie un log à sa trace, pour passer de l’un à l’autre.
AttributsTout ce que vous ajoutez, comme customer.id ou http.route. Chacun devient un filtre.

Les attributs qui commencent par instatus. sont réservés et remplacés à l’arrivée des données.

Dépannage

Vous voyezSolution
401Vérifiez la clé et l’en-tête X-Instatus-Site-Id. Le titulaire de la clé doit être propriétaire, administrateur ou éditeur de la page.
400Le corps n’est pas un OTLP valide. Vérifiez Content-Type et la structure JSON du log de test.
429Le volume de données du mois est épuisé. Voir forfaits et limites.
200, mais rien ne s’afficheAttendez quelques secondes, puis vérifiez la période. Un log daté dans le passé n’apparaît que si la période le couvre.
Rien du toutLes SDK envoient par lots. Assurez-vous que votre app vide ou arrête le provider avant de se terminer.

Régénérer votre clé d’API dans les paramètres développeur désactive aussitôt l’ancienne. Mettez donc d’abord à jour chaque app qui l’utilise.