Usar rastreamentos do lado do cliente

Nesta página, descrevemos como ativar traces do lado do cliente com o OpenTelemetry ao usar as bibliotecas de cliente do Cloud Storage para interagir com o Cloud Storage. É possível coletar e visualizar dados de trace usando as seguintes bibliotecas de cliente do Cloud Storage compatíveis:

Visão geral

Ativar traces nas bibliotecas de cliente do Cloud Storage permite monitorar o desempenho, identificar problemas de latência e realizar depurações rapidamente para solicitações do Cloud Storage. Os traces permitem ver a sequência de uma solicitação concluída, fornecendo uma visão detalhada de como a solicitação foi recebida, gerenciada e respondida pelo Cloud Storage. Um único trace é composto por vários períodos, que são registros detalhados com carimbo de data/hora de cada função ou operação que o aplicativo realizou durante a solicitação do Cloud Storage.

Vantagens

A coleta e a propagação de dados de trace oferecem os seguintes benefícios ao seu aplicativo:

  • Maior visibilidade do desempenho: como os dados de trace são gerados quase em tempo real à medida que o Cloud Storage conclui cada solicitação, é possível identificar rapidamente gargalos no desempenho e detectar problemas de latência.

  • Tratamento de erros: é possível identificar onde os problemas surgem, acelerando a análise da causa raiz e reduzindo o tempo de inatividade usando as informações sobre cada solicitação do Cloud Storage fornecida em um trace.

Como funcionam os traces do lado do cliente

As seções a seguir mostram em detalhes como funciona a coleta de traces.

Como funciona a coleta de traces com o OpenTelemetry

As bibliotecas de cliente do Cloud Storage oferecem suporte à coleta de dados de trace usando o SDK do OpenTelemetry para configurar os seguintes componentes necessários para coletar e propagar dados de trace:

  • Provedor de trace: usado pelas bibliotecas de cliente do Cloud Storage, o provedor de trace é responsável por criar e gerenciar o sistema de trace, incluindo a geração e o gerenciamento de traces e períodos no aplicativo.

  • Exportador de trace: usado pelo SDK do OpenTelemetry, o exportador de trace é responsável por enviar dados de trace para uma plataforma de observabilidade de back-end, como o Cloud Trace, em que é possível analisar e visualizar dados de trace. Para saber mais sobre o exportador de trace, consulte Como funcionam os exportadores de trace.

Como funcionam os exportadores de trace

A configuração de traces usando o SDK do OpenTelemetry inclui a seleção de um back-end de observabilidade para exportar os dados para onde eles são analisados, armazenados e visualizados. Embora seja possível exportar os dados de trace para qualquer back-end de observabilidade de sua escolha, recomendamos o uso do Cloud Trace, que pode ser acessado pelo console do Google Cloud e oferece integração com outros serviços do Google Cloud .

Depois que o provedor e o exportador de trace forem configurados e ativados, será possível visualizar os dados de trace quase em tempo real, conforme os traces e períodos são gerados para cada solicitação do Cloud Storage.

Usando o explorador do Cloud Trace no console doGoogle Cloud , é possível visualizar cada trace que contém o seguinte:

  • Uma visão geral de uma solicitação do Cloud Storage de ponta a ponta.

  • Vários períodos, cada um capturando uma única operação com carimbo de data/hora na solicitação do Cloud Storage que foi realizada.

Para saber mais sobre traces e períodos, consulte a documentação do OpenTelemetry sobre traces e períodos.

Preços

Os dados de trace estão sujeitos a cobrança. As cobranças são baseadas no número de períodos de trace ingeridos e verificados pelo Cloud Trace. Para saber mais sobre os períodos de trace cobráveis e exemplos de preços, consulte Custos do Cloud Trace.

Antes de começar

Antes de coletar traces do uso da API Cloud Storage, conclua as seguintes etapas:

  1. Instale a biblioteca de cliente do Cloud Storage.

  2. Configure a autenticação.

  3. Ative a API Cloud Trace, se ainda não tiver feito isso.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  4. Ative a API Storage do Cloud Storage.

    Ativar a API

Funções exigidas

Para receber a permissão necessária para gravar traces no Cloud Trace, peça ao administrador para conceder a você o papel do IAM de Agente do Cloud Trace (roles/cloudtrace.agent) no projeto usado pelo cliente.

Esse papel predefinido contém a permissão cloudtrace.traces.patch, que é necessária para gravar traces no Cloud Trace.

Também é possível receber essas permissões com papéis predefinidos ou criar papéis personalizados para conceder permissões específicas. Para instruções sobre como conceder papéis em projetos, consulte Conceder ou revogar um papel. Para mais informações sobre o papel de agente do Cloud Trace, consulte a documentação do Identity and Access Management (IAM).

Configurar o rastreamento do aplicativo

Siga as instruções abaixo para configurar o trace e começar a coletar dados de trace usando a biblioteca de cliente do Cloud Storage:

C++

  1. Instale as seguintes versões:

    • Biblioteca de cliente C++ versão v2.16.0 ou mais recente

    • C++ versão 14 ou mais recente

  2. Para ativar a instrumentação de rastreamento do OpenTelemetry na biblioteca de cliente C++, atualize a configuração do sistema de build para CMake ou Bazel.

  3. Crie uma instância do cliente do Cloud Storage com os traces do OpenTelemetry ativados. 

    #include "google/cloud/opentelemetry/configure_basic_tracing.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/opentelemetry_options.h"
#include <iostream>

int main(int argc, char* argv[]) {
  if (argc != 3) {
    std::cerr << "Usage: " << argv[0] << " <bucket-name> <project-id>\n";
    return 1;
  }
  std::string const bucket_name = argv[1];
  std::string const project_id = argv[2];

  // Create aliases to make the code easier to read.
  namespace gc = ::google::cloud;
  namespace gcs = ::google::cloud::storage;

  // Instantiate a basic tracing configuration which exports traces to Cloud
  // Trace. By default, spans are sent in batches and always sampled.
  auto project = gc::Project(project_id);
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Create a client with OpenTelemetry tracing enabled.
  auto options = gc::Options{}.set<gc::OpenTelemetryTracingOption>(true);
  auto client = gcs::Client(options);

  auto writer = client.WriteObject(bucket_name, "quickstart.txt");
  writer << "Hello World!";
  writer.Close();
  if (!writer.metadata()) {
    std::cerr << "Error creating object: " << writer.metadata().status()
              << "\n";
    return 1;
  }
  std::cout << "Successfully created object: " << *writer.metadata() << "\n";

  auto reader = client.ReadObject(bucket_name, "quickstart.txt");
  if (!reader) {
    std::cerr << "Error reading object: " << reader.status() << "\n";
    return 1;
  }

  std::string contents{std::istreambuf_iterator<char>{reader}, {}};
  std::cout << contents << "\n";

  // The basic tracing configuration object goes out of scope. The collected
  // spans are flushed to Cloud Trace.

  return 0;
}

Java

  1. Instale as seguintes versões da biblioteca de cliente do Cloud Storage para Java:

    • com.google.cloud:google-cloud-storage:2.47.0 ou posterior

    • com.google.cloud:libraries-bom:26.53.0 ou posterior

  2. Instale o exportador do Cloud Trace para OpenTelemetry. Também é possível usar qualquer exportador de sua escolha.

  3. Instale o propagador do Cloud Trace.

  4. Crie uma instância do cliente do Cloud Storage com os traces do OpenTelemetry ativados.

    public class QuickstartOpenTelemetrySample {
  public static void main(String... args) throws Exception {
    SpanExporter spanExporter = TraceExporter.createWithDefaultConfiguration();
    TextMapPropagator propagators =
        TextMapPropagator.composite(
            W3CTraceContextPropagator.getInstance(),
            new XCloudTraceContextPropagator(/* oneway= */ true));

    OpenTelemetrySdk openTelemetry =
        OpenTelemetrySdk.builder()
            .setPropagators(ContextPropagators.create(propagators))
            .setTracerProvider(
                SdkTracerProvider.builder()
                    // Sample Rate is set to alwaysOn
                    // It is recommended to sample based on a ratio for standard use ie.
                    // .setSampler(Sampler.traceIdRatioBased(0.2)) // sample only 20% of trace ids
                    .setSampler(Sampler.alwaysOn())
                    .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
                    .build())
            .build();
    StorageOptions options = StorageOptions.newBuilder().setOpenTelemetry(openTelemetry).build();
    Storage storage = options.getService();
    System.out.println("Created an instance of storage with OpenTelemetry configured");
  }
}

Python

  1. Instale a biblioteca de cliente do Cloud Storage para Python:

    pip install google-cloud-storage[tracing]>=2.18.0

  2. Instale o exportador e o propagador do Cloud Trace. Também é possível usar qualquer exportador de sua escolha.

    pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp

  3. Instale a instrumentação de solicitações do OpenTelemetry para rastrear as solicitações HTTP subjacentes.

    pip install opentelemetry-instrumentation-requests

  4. Defina a variável de ambiente para ativar seletivamente o rastreamento do cliente de armazenamento do Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configure o exportador e o provedor de trace. 

    
from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.resourcedetector.gcp_resource_detector import (
    GoogleCloudResourceDetector,
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
# Optional: Enable traces emitted from the requests HTTP library.
from opentelemetry.instrumentation.requests import RequestsInstrumentor

from google.cloud import storage

# The ID of your GCS bucket
# bucket_name = "your-bucket-name"
# The ID of your GCS object
# blob_name = "your-object-name"
# The contents to upload to the file
# data = "The quick brown fox jumps over the lazy dog."

# In this sample, we use Google Cloud Trace to export the OpenTelemetry
# traces: https://cloud.google.com/trace/docs/setup/python-ot
# Choose and configure the exporter for your environment.

tracer_provider = TracerProvider(
    # Sampling is set to ALWAYS_ON.
    # It is recommended to sample based on a ratio to control trace ingestion volume,
    # for instance, sampler=TraceIdRatioBased(0.2)
    sampler=ALWAYS_ON,
    resource=GoogleCloudResourceDetector().detect(),
)

# Export to Google Cloud Trace.
tracer_provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Optional: Enable traces emitted from the requests HTTP library.
RequestsInstrumentor().instrument(tracer_provider=tracer_provider)

# Get the tracer and create a new root span.
tracer = tracer_provider.get_tracer("My App")
with tracer.start_as_current_span("trace-quickstart"):
    # Instantiate a storage client and perform a write and read workload.
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    blob.upload_from_string(data)
    print(f"{blob_name} uploaded to {bucket_name}.")

    blob.download_as_bytes()
    print("Downloaded storage object {} from bucket {}.".format(blob_name, bucket_name))

Visualizar os rastros

Use o explorador do Cloud Trace para ver os dados de trace no console do Google Cloud :

  1. No console Google Cloud , acesse a página Explorador de traces:

    Acessar o Explorador de traces

    Também é possível encontrar essa página usando a barra de pesquisa.

  2. Na página Explorador de traces, clique em um trace específico no gráfico de dispersão para ver os detalhes dele.

    O painel Detalhes do trace mostra uma tabela de períodos de trace.

  3. Opcional: clique em uma linha de período para ver informações detalhadas sobre um período específico, como:

    • Atributos: pares de chave-valor que fornecem mais informações sobre o período.

    • Registros e eventos: entradas de registro associadas ao período.

    • Stack traces: stack traces associados ao período.

    • Metadados e links: links para outros serviços do Google Cloud associados ao período.

Para mais informações sobre como usar o explorador do Cloud Trace, consulte Encontrar e explorar traces.

A seguir