Usar rastreamentos do lado do cliente

Nesta página, descrevemos como ativar traces do lado do cliente com 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:

Visão geral

A ativação de traces nas bibliotecas de cliente do Cloud Storage permite monitorar a performance, identificar problemas de latência e realizar a depuração rapidamente para solicitações do Cloud Storage. Os traces permitem visualizar 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 e com carimbo de data/hora de cada função ou operação que o aplicativo realizou durante a solicitação do Cloud Storage.

Benefícios

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

  • Visibilidade de performance aprimorada: como os dados de trace são gerados quase em tempo real à medida que o Cloud Storage conclui cada solicitação feita, é possível identificar rapidamente gargalos na performance 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 os traces do lado do cliente funcionam

As seções a seguir fornecem uma visão detalhada de como a coleta de traces funciona.

Como a coleta de traces funciona 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 rastreamento, 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 os exportadores de trace funcionam.

Como os exportadores de trace funcionam

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 análise, armazenamento e visualização. 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 usando o Google Cloud console e oferece integração com outros Google Cloud serviços.

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 à medida que os traces e períodos forem gerados para cada solicitação do Cloud Storage.

Usando o explorador do Cloud Trace no Google Cloud console, é 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 são cobrados. As cobranças são baseadas no número de períodos de trace ingeridos e verificados pelo Cloud Trace. Para saber mais sobre períodos de trace sujeitos a cobrança e exemplos de preços, consulte Custos do Cloud Trace.

Antes de começar

Antes de coletar traces para o uso da API Storage do Cloud Storage, conclua as etapas a seguir:

  1. Instale a biblioteca de cliente do Cloud Storage.

  2. Configure a autenticação.

  3. Ative a API Cloud Trace.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. 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 cloudtrace.traces.patch permissão, que é necessária para gravar traces no Cloud Trace.

Essas permissões também podem ser concedidas com papéis predefinidos ou é possível criar funções personalizadas 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

Use as instruções a seguir para configurar o rastreamento 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 do 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 do 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 Java:

    • com.google.cloud:google-cloud-storage:2.47.0 ou mais recente

    • com.google.cloud:libraries-bom:26.53.0 ou mais recente

  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 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 visualizar os dados de trace no Google Cloud console:

  1. No Google Cloud console, 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 visualizar os detalhes do trace.

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

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

    • Atributos: pares de chave-valor que fornecem informações adicionais 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 Google Cloud serviços associados ao período.

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

A seguir