Gravar registros OTLP na API Telemetry

Este documento mostra como enviar registros OTLP diretamente para o endpoint de registro da API Telemetry (OTLP), telemetry.googleapis.com, e como visualizar as entradas de registro ingeridas no Cloud Logging.

Antes de começar

Esta seção descreve como configurar seu ambiente para usar a API Telemetry.

Selecionar ou criar um Google Cloud projeto

Escolha um Google Cloud projeto para este exemplo. Se você ainda não tiver um projeto, crie um: Google Cloud

  1. Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  2. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

Configurar o gcloud

A ferramenta gcloud faz parte da Google Cloud CLI. Para mais informações sobre como instalá-la, consulte Como gerenciar componentes da CLI do Google Cloud. Para ver os componentes da CLI gcloud que você instalou, execute o seguinte comando:

gcloud components list

Para configurar a CLI gcloud para uso, execute os comandos a seguir depois de substituir a variável PROJECT_ID pelo identificador do seu Google Cloud projeto.

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

Ativar APIs

Ative a API Cloud Logging e a API Telemetry no seu Google Cloud projeto. Preste atenção especial à API Telemetry, telemetry.googleapis.com; este documento pode ser a primeira vez que você encontra essa API.

Se as APIs aparecerem na saída do comando a seguir, elas já estarão ativadas:

gcloud services list

Se uma das APIs não estiver ativada, execute o comando correspondente:

gcloud services enable logging.googleapis.com
gcloud services enable telemetry.googleapis.com

Receber permissão para gravar registros

Para receber as permissões necessárias para gravar registros na API Telemetry e visualizar as entradas de registro criadas, peça ao administrador que conceda a você os seguintes papéis do IAM na sua principal:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Gravar registros OTLP usando a API Telemetry

Esta seção descreve como criar um registro de registro formatado em OTLP e enviá-lo para a API Telemetry usando o utilitário curl.

Criar um registro OTLP

Crie um arquivo JSON que contenha um registro de registro formatado em OTLP. As guias a seguir contêm um registro de registro muito simples e um registro mais complexo de vários registros. Você pode escolher um ou outro ou enviar cada um em sucessão.

Registro OTLP simples 

{
  "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." },
          }
        ]
      }
      ]
    }
  ]
}

Registro OTLP mais complexo 

{
  "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}},
             ]
          }
        ]
      }
      ]
    }
  ]
}

Copie o conteúdo JSON de uma das guias para um arquivo e salve-o.

Esses dois exemplos de JSON resultam em entradas de registro do Cloud Logging que são gravadas no tipo de recurso monitorado gce_instance. Cada item logRecord na matriz scopedLogs se torna uma entrada de registro separada do Cloud Logging em um registro nomeado para o valor do campo eventName no registro de registro OTLP. Para mais informações sobre como os registros OTLP são mapeados para entradas de registro do Logging, consulte o seguinte:

Enviar o registro para a API Telemetry

Depois de substituir a variável OTLP_LOG_JSON_FILE pelo nome do arquivo que você criou, use o comando curl a seguir para postar o conteúdo do arquivo no endpoint de registro da 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"

Se você criar vários arquivos de registros JSON, mude a OTLP_LOG_JSON_FILE variável no curl comando.

O comando curl produz uma sequência de mensagens e, se for bem-sucedido, uma resposta vazia ({}). A saída é semelhante a esta:

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

{}

Visualizar registros OTLP ingeridos

É possível visualizar as entradas de registro resultantes dos registros OTLP usando qualquer uma das ferramentas do Cloud Logging, incluindo a Análise de registros e o Observability Analytics. As seções a seguir descrevem como visualizar entradas de registro usando o seguinte:

Usar gcloud para visualizar registros

É possível recuperar as entradas de registro que você acabou de criar usando o gcloud logging read comando. O comando a seguir restringe a saída às entradas de registro no registro otlp-test-log que foram gravadas nos últimos cinco minutos:

gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json

As entradas de registro que correspondem aos registros OTLP de amostra são semelhantes a estas:

Entrada de registro simples 

[
  {
    "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"
  }
]

Entradas de registro mais complexas 

[
  {
    "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"
  }
]

Usar a Análise de registros para visualizar registros

Para visualizar as entradas de registro criadas nos registros OTLP no Google Cloud console, faça o seguinte:

  1. No Google Cloud console do, acesse a página segmento Análise de registros:

    Acessar a Análise de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

  2. Selecione o Google Cloud projeto para o qual você enviou os registros OTLP.

  3. Use o painel Consulta para inserir uma consulta. Os exemplos neste documento são gravados em um registro chamado otlp-test-log. Para pesquisar entradas nesse registro, insira a seguinte consulta:

    LOG_ID(otlp-test-log)

  4. Clique em Executar consulta

Limpar

Se você criou um projeto e não precisa mais dele, então você pode excluir o projeto para evitar cobranças na sua Google Cloud conta.

A seguir

Para saber mais sobre a API Telemetry, consulte os seguintes documentos:

  • A visão geral da API descreve a API Telemetry para registros, métricas e rastros.
  • v1.logs descreve o endpoint da API Telemetry para registro e fornece informações detalhadas sobre como os registros OTLP são ingeridos como entradas de registro do Cloud Logging.