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 seguintes etapas:

  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, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pela função de proprietário (roles/owner). Caso contrário, é possível receber essa permissão pela função de administrador do uso de serviços (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.

    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ê opapel de agente do Cloud Trace (roles/cloudtrace.agent) do IAM 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.

Também é possível receber essas permissões com funções predefinidas ou criar funções personalizadas para conceder permissões específicas. Para instruções sobre como conceder funções 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 para seu 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 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 Java do Cloud Storage:

    • 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 Python do Cloud Storage:

    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