Gravar registros OTLP na API Telemetry

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

Antes de começar

Nesta seção, descrevemos como configurar seu ambiente para usar a API Telemetry.

Selecione ou crie um projeto do Google Cloud

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

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de 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 gcloud

A ferramenta gcloud faz parte da Google Cloud CLI. Para informações sobre como instalar, 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 projetoGoogle Cloud .

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 projetoGoogle Cloud . 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 seguinte comando, elas já estarão ativadas:

gcloud services list

Se alguma 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 ter as permissões necessárias para gravar registros na API Telemetry e visualizar as entradas de registro criadas, peça ao administrador para conceder a você os seguintes papéis do IAM no seu 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 papéis personalizados ou outros papéis predefinidos.

Escrever registros OTLP usando a API Telemetry

Nesta seção, descrevemos como criar um registro de log formatado em OTLP e enviar o registro para a API Telemetry usando o utilitário curl.

Criar um registro OTLP

Crie um arquivo JSON que contenha um registro de log formatado em OTLP. As guias a seguir contêm um registro de log muito simples e um registro de log mais complexo e múltiplo. Você pode escolher uma ou outra ou enviar cada uma 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 qualquer uma das guias para um arquivo e salve-o.

Os 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 com o valor do campo eventName no registro de log OTLP. Para mais informações sobre como os registros OTLP são mapeados para entradas de registro do Logging, consulte:

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 seguinte comando curl para postar o conteúdo do arquivo no endpoint de geração de registros 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 de log JSON, mude a variável OTLP_LOG_JSON_FILE no comando curl.

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

{}

Ver registros OTLP ingeridos

É possível conferir as entradas de registro resultantes dos seus 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:

Usar gcloud para ver registros

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

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

As entradas de registro correspondentes aos registros de exemplo do OTLP 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 ver os registros

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

  1. No console do Google Cloud , acesse a página 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 projeto do Google Cloud para onde 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, exclua o projeto para evitar cobranças na sua conta do Google Cloud .

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 rastreamentos.
  • v1.logs descreve o endpoint da API Telemetry para geração de registros e fornece informações detalhadas sobre como os registros de log OTLP são ingeridos como entradas de registro do Cloud Logging.