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électionnez ou créez un projet Google Cloud .
Choisissez un projet Google Cloud pour cet exemple. Si vous n'avez pas encore de projet Google Cloud , créez-en un :
- Connectez-vous à votre compte Google Cloud . 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 Gérer les composants de Google Cloud CLI.
Pour afficher les composants de la 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 votre projetGoogle Cloud .
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 projetGoogle Cloud . Portez une attention particulière à l'API Telemetry, telemetry.googleapis.com. C'est peut-être la première fois que vous rencontrez cette API.
Si les API apparaissent dans le résultat de la commande suivante, cela signifie qu'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 compte 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 multiple plus complexe. Vous pouvez choisir l'une ou l'autre, ou les envoyer l'une après l'autre.
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 é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 dans 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 des enregistrements de journaux OTLP aux entrée de journal journaux
- 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 sur 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 journaux JSON, veillez à modifier la variable OTLP_LOG_JSON_FILE dans la commande curl.
La commande curl génère une séquence de messages et, en cas de succès, une réponse vide ({}). La sortie ressemble à ce qui 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 décrivent 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 commande gcloud logging read.
La commande suivante limite la sortie 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 qui correspondent 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 console Google Cloud , procédez comme suit :
-
Dans la console Google Cloud , accédez à la pageExplorateur 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 projet Google Cloud 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.
Effectuer un nettoyage
Si vous avez créé un projet et que vous n'en avez plus besoin, vous pouvez le supprimer pour éviter que des frais ne soient facturés sur votre compte Google Cloud .
Étapes suivantes
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 journaux OTLP sont ingérés en tant qu'entrées de journal Cloud Logging.