Usar rastros do lado do cliente

Nesta página, descrevemos como ativar rastreamentos 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 rastreamento usando as seguintes bibliotecas de cliente do Cloud Storage compatíveis:

Visão geral

Ao ativar os rastreamentos nas bibliotecas de cliente do Cloud Storage, você pode monitorar o desempenho, identificar problemas de latência e realizar a depuração rapidamente para solicitações do Cloud Storage. Os rastreamentos 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 rastreamento é composto de vários intervalos, 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.

Vantagens

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

  • Visibilidade aprimorada da performance: como os dados de rastreamento são gerados em quase 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 fornecidas em um rastreamento.

Como os rastreamentos do lado do cliente funcionam

As seções a seguir explicam detalhadamente como funciona a coleta de rastreamentos.

Como a coleta de rastreamentos funciona com o OpenTelemetry

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

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

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

Como os exportadores de rastreamento funcionam

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

Depois que o provedor e o exportador de rastreamento forem configurados e ativados, você poderá ver os dados de rastreamento quase em tempo real à medida que os rastreamentos e períodos forem gerados para cada solicitação do Cloud Storage.

Usando o explorador do Cloud Trace no Google Cloud console, é possível ver cada rastreamento que contém o seguinte:

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

  • Vários intervalos, 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 rastreamentos e intervalos, consulte a documentação do OpenTelemetry sobre rastreamentos e intervalos.

Preços

Os dados de rastreamento sã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 intervalos de rastreamento faturáveis e exemplos de preços, consulte Custos do Cloud Trace.

Antes de começar

Antes de coletar rastreamentos para seu uso da API Cloud Storage, conclua as etapas a seguir:

  1. Instale a biblioteca de cliente do Cloud Storage.

  2. Configure a autenticação.

  3. Enable the Cloud Trace API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  4. Ative a API Cloud Storage.

    Ativar a API

Funções exigidas

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

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

Essas permissões também podem ser concedidas com papéis predefinidos, ou você pode 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 a função do agente do Cloud Trace, consulte a documentação do Identity and Access Management (IAM).

Configurar o rastreamento para seu aplicativo

Siga estas instruções para configurar o rastreamento e começar a coletar dados de rastreamento 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 rastreamentos 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 posterior

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

  2. Instale o exportador do Cloud Trace para OpenTelemetry. Você também pode usar qualquer exportador da sua escolha.

  3. Instale o propagador do Cloud Trace.

  4. Crie uma instância do cliente do Cloud Storage com rastreamentos 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. Você também pode usar qualquer exportador da 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 Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configure o exportador e o provedor de rastreamento. 

    
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 rastreamento no console 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 diagrama de dispersão para conferir 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 informações adicionais sobre o intervalo.

    • Registros e eventos: entradas de registro associadas ao intervalo.

    • Stack traces: stack traces associados ao intervalo.

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

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

A seguir