Ce document explique comment envoyer des journaux OTLP directement au point de terminaison de journalisation
de l'API Telemetry (OTLP),
telemetry.googleapis.com, et comment afficher les entrées de journal ingérées dans
Cloud Logging.
Avant de commencer
Cette section explique comment configurer votre environnement pour utiliser l'API Telemetry.
Sélectionner ou créer un Google Cloud projet
Choisissez un Google Cloud projet pour cet exemple. Si vous n'en avez pas déjà un Google Cloud , créez-en un :
- Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Configurer gcloud
L'outil gcloud fait partie de Google Cloud CLI. Pour en savoir plus sur son installation, consultez la page
Gérer les composants de Google Cloud CLI.
Pour afficher les composants de gcloud CLI que vous avez installés, exécutez la commande suivante :
gcloud components list
Pour configurer la gcloud CLI, exécutez les commandes suivantes après avoir remplacé la variable PROJECT_ID par l'identifiant de votreGoogle Cloud projet.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID gcloud auth login gcloud config set project PROJECT_ID
Activer les API
Activez l'API Cloud Logging et l'API Telemetry dans votre
Google Cloud projet. Portez une attention particulière à l'
API Telemetry, telemetry.googleapis.com : vous la découvrez peut-être pour la première fois.
Si les API apparaissent dans le résultat de la commande suivante, elles sont déjà activées :
gcloud services list
Si l'une des API n'est pas activée, exécutez la commande correspondante :
gcloud services enable logging.googleapis.com gcloud services enable telemetry.googleapis.com
Obtenir l'autorisation d'écrire des journaux
Pour obtenir les autorisations nécessaires pour écrire des journaux dans l'API Telemetry et afficher les entrées de journal créées, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre principal :
- Lecteur de journaux (
roles/logging.viewer) - Rédacteur de journaux (
roles/logging.logWriter)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.
Écrire des journaux OTLP à l'aide de l'API Telemetry
Cette section explique comment créer un enregistrement de journal au format OTLP et l'envoyer à l'API Telemetry à l'aide de l'utilitaire curl.
Créer un journal OTLP
Créez un fichier JSON contenant un enregistrement de journal au format OTLP. Les onglets suivants contiennent un enregistrement de journal très simple et un enregistrement de journal plus complexe, comportant plusieurs journaux. Vous pouvez choisir l'un ou l'autre, ou envoyer chacun d'eux successivement.
Journal OTLP simple
{
"resourceLogs": [
{
"resource": {
"attributes": [
{"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
{"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
{"key": "zone", "value": {"stringValue": "us-central1"}},
{"key": "instance_id", "value": {"stringValue": "12345"}},
]
},
"scopeLogs": [
{
"logRecords": [
{ "eventName": "otlp-test-log",
"body": { "stringValue": "This is a trivial log message." },
}
]
}
]
}
]
}
Journal OTLP plus complexe
{
"resourceLogs": [
{
"resource": {
"attributes": [
{"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
{"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
{"key": "zone", "value": {"stringValue": "us-central1"}},
{"key": "instance_id", "value": {"stringValue": "12345"}},
]
},
"scopeLogs": [
{
"logRecords": [
{ "eventName": "otlp-test-log",
"severityText": "INFO",
"body": { "stringValue": "This is an informational message." },
"attributes": [
{"key": "string.attribute",
"value": { "stringValue": "Here's some general info."}},
{"key": "int.attribute",
"value": { "intValue": "666"}},
{"key": "double.attribute",
"value": { "doubleValue": "3.14159"}},
{"key": "boolean.attribute",
"value": { "boolValue": true}},
]
},
{ "eventName": "otlp-test-log",
"severityText": "DEBUG",
"body": { "stringValue": "This is a debug message." },
"attributes": [
{"key": "string.attribute",
"value": { "stringValue": "Here's some debug info."}},
{"key": "int.attribute",
"value": { "intValue": "42"}},
{"key": "double.attribute",
"value": { "doubleValue": "6373.392"}},
{"key": "boolean.attribute",
"value": { "boolValue": false}},
]
}
]
}
]
}
]
}
Copiez le contenu JSON de l'un des onglets dans un fichier, puis enregistrez-le.
Ces deux exemples JSON génèrent des entrées de journal Cloud Logging qui
sont écrites par rapport au type de ressource surveillée gce_instance. Chaque élément logRecord du tableau scopedLogs devient une entrée de journal Cloud Logging distincte dans un journal nommé d'après la valeur du champ eventName de l'enregistrement de journal OTLP.
Pour en savoir plus sur la façon dont les journaux OTLP sont mappés aux entrées de journal Logging, consultez les ressources suivantes :
- Mappage d'un enregistrement de journal OTLP à une entrée de journal
- Mappage des attributs OTLP au type de ressource
Envoyer le journal à l'API Telemetry
Après avoir remplacé la variable OTLP_LOG_JSON_FILE par le nom du fichier que vous
avez créé, utilisez la commande curl suivante pour publier le contenu du fichier dans
le point de terminaison de journalisation de l'API Telemetry,
https://telemetry.googleapis.com/v1/logs :
curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJECT_ID}" \
-d @OTLP_LOG_JSON_FILE \
"https://telemetry.googleapis.com/v1/logs"
Si vous créez plusieurs fichiers d'enregistrements de journal JSON, veillez à modifier la
OTLP_LOG_JSON_FILE variable dans la curl commande.
La commande curl génère une séquence de messages et, en cas de réussite, une réponse vide ({}). Le résultat se présente comme suit :
HTTP/2 200
x-google-esf-cloud-client-params: backend_service_name: "telemetry.googleapis.com" backend_fully_qualified_method: "opentelemetry.proto.collector.logs.v1.LogsService.Export"
[...]
x-google-gfe-response-code-details-trace: response_code_set_by_backend
x-google-gfe-response-body-transformations: gunzipped,chunked
x-google-shellfish-status: CA0gBEBG
x-google-gfe-version: 2.970.1
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
accept-ranges: none
{}
Afficher les journaux OTLP ingérés
Vous pouvez afficher les entrées de journal résultant de vos journaux OTLP à l'aide de n'importe quel outil Cloud Logging, y compris l'explorateur de journaux et Observability Analytics. Les sections suivantes expliquent comment afficher les entrées de journal à l'aide des éléments suivants :
Utiliser gcloud pour afficher les journaux
Vous pouvez récupérer les entrées de journal que vous venez de créer à l'aide de la
gcloud logging read commande.
La commande suivante limite le résultat aux entrées de journal du journal otlp-test-log qui ont été écrites au cours des cinq dernières minutes :
gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json
Les entrées de journal correspondant aux exemples de journaux OTLP se présentent comme suit :
Entrée de journal simple
[
{
"insertId": "1yt9bu7a0",
"logName": "projects/PROJECT_ID/logs/otlp-test-log",
"otel": {
"resource": {
"attributes": {
"cloud.platform": "gcp_compute_engine",
"gcp.project_id": "PROJECT_ID",
"instance_id": "12345",
"zone": "us-central1"
}
}
},
"receiveTimestamp": "2026-03-18T20:17:00.128801819Z",
"resource": {
"labels": {
"instance_id": "12345",
"project_id": "PROJECT_ID",
"zone": "us-central1"
},
"type": "gce_instance"
},
"textPayload": "This is a trivial log message.",
"timestamp": "2026-03-18T20:17:00.128801819Z"
}
]
Entrées de journal plus complexes
[
{
"insertId": "1aw7fsja1",
"labels": {
"boolean.attribute": "false",
"double.attribute": "6373.39",
"int.attribute": "42",
"string.attribute": "Here's some debug info."
},
"logName": "projects/PROJECT_ID/logs/otlp-test-log",
"otel": {
"resource": {
"attributes": {
"cloud.platform": "gcp_compute_engine",
"gcp.project_id": "PROJECT_ID",
"instance_id": "12345",
"zone": "us-central1"
}
}
},
"receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
"resource": {
"labels": {
"instance_id": "12345",
"project_id": "PROJECT_ID",
"zone": "us-central1"
},
"type": "gce_instance"
},
"severity": "DEBUG",
"textPayload": "This is a debug message.",
"timestamp": "2026-03-16T17:11:19.461096569Z"
},
{
"insertId": "1aw7fsja0",
"labels": {
"boolean.attribute": "true",
"double.attribute": "3.14159",
"int.attribute": "666",
"string.attribute": "Here's some general info."
},
"logName": "projects/PROJECT_ID/logs/otlp-test-log",
"otel": {
"resource": {
"attributes": {
"cloud.platform": "gcp_compute_engine",
"gcp.project_id": "PROJECT_ID",
"instance_id": "12345",
"zone": "us-central1"
}
}
},
"receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
"resource": {
"labels": {
"instance_id": "12345",
"project_id": "PROJECT_ID",
"zone": "us-central1"
},
"type": "gce_instance"
},
"severity": "INFO",
"textPayload": "This is an informational message.",
"timestamp": "2026-03-16T17:11:19.461096569Z"
}
]
Utiliser l'explorateur de journaux pour afficher les journaux
Pour afficher les entrées de journal créées à partir de vos journaux OTLP dans la Google Cloud console, procédez comme suit :
-
Dans la Google Cloud console, accédez à la Explorateur de journaux :
Accéder à l'explorateur de journaux
Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
- Sélectionnez le Google Cloud projet auquel vous avez envoyé vos journaux OTLP.
Utilisez le volet Requête pour saisir une requête. Les exemples de ce document sont écrits dans un journal nommé
otlp-test-log. Pour rechercher des entrées dans ce journal, saisissez la requête suivante :LOG_ID(otlp-test-log)Cliquez sur Exécuter la requête.
Libérer de l'espace
Si vous avez créé un projet et que vous n'en avez plus besoin, vous pouvez supprimer le projet pour éviter d'être facturé sur votre Google Cloud compte.
Étape suivante
Pour en savoir plus sur l'API Telemetry, consultez les documents suivants :
- La présentation de l'API décrit l'API Telemetry pour les journaux, les métriques et les traces.
- v1.logs décrit le point de terminaison de l'API Telemetry pour la journalisation et fournit des informations détaillées sur la façon dont les enregistrements de journal OTLP sont ingérés en tant qu'entrées de journal Cloud Logging.