Use rastreios do lado do cliente

Esta página descreve como ativar rastreios do lado do cliente com o OpenTelemetry quando usa as bibliotecas cliente do Cloud Storage para interagir com o Cloud Storage. Pode recolher e ver dados de rastreio através das seguintes bibliotecas de cliente do Cloud Storage suportadas:

Vista geral

A ativação dos rastreios nas bibliotecas de cliente do Cloud Storage permite-lhe monitorizar o desempenho, identificar problemas de latência e realizar rapidamente a depuração de pedidos do Cloud Storage. Os rastreios permitem-lhe ver a sequência de um pedido concluído, fornecendo uma vista detalhada de como o pedido foi recebido, gerido e respondido pelo Cloud Storage. Um único rastreio é composto por vários intervalos, que são registos detalhados com data/hora de cada função ou operação que a sua aplicação realizou ao longo do pedido do Cloud Storage.

Vantagens

A recolha e a propagação de dados de rastreio oferecem as seguintes vantagens à sua aplicação:

  • Visibilidade do desempenho melhorada: uma vez que os dados de rastreio são gerados em tempo quase real à medida que o Cloud Storage conclui cada pedido que faz, pode identificar rapidamente gargalos no desempenho e detetar problemas de latência.

  • Processamento de erros: pode identificar onde surgem problemas, acelerar a análise da causa principal e reduzir o tempo de inatividade através das informações sobre cada pedido do Cloud Storage fornecidas num rastreio.

Como funcionam os rastreios do lado do cliente

As secções seguintes fornecem uma análise detalhada do funcionamento da recolha de rastreios.

Como funciona a recolha de rastreios com o OpenTelemetry

As bibliotecas de cliente do Cloud Storage suportam a recolha de dados de rastreio através do SDK OpenTelemetry para configurar os seguintes componentes necessários para recolher e propagar dados de rastreio:

  • Fornecedor de rastreio: usado pelas bibliotecas cliente do Cloud Storage, o fornecedor de rastreio é responsável por criar e gerir o sistema de rastreio, incluindo a geração e a gestão de rastreios e intervalos na sua aplicação.

  • Exportador de rastreios: usado pelo SDK OpenTelemetry, o exportador de rastreios é responsável pelo envio de dados de rastreios para uma plataforma de observabilidade de back-end como o Cloud Trace, onde pode analisar e visualizar dados de rastreios. Para saber mais sobre o exportador de rastreios, consulte o artigo Como funcionam os exportadores de rastreios.

Como funcionam os exportadores de rastreios

A configuração de rastreios através do SDK OpenTelemetry inclui a seleção de um back-end de observabilidade para exportar os seus dados para onde são analisados, armazenados e visualizados. Embora possa exportar os dados de rastreio para qualquer back-end de observabilidade à sua escolha, recomendamos a utilização do Cloud Trace, ao qual pode aceder através da Google Cloud consola e que oferece integração com outros Google Cloud serviços.

Depois de configurar e ativar o fornecedor de rastreio e o exportador de rastreio, pode ver os dados de rastreio quase em tempo real à medida que os rastreios e os intervalos são gerados para cada pedido do Cloud Storage.

Com o explorador do Cloud Trace na Google Cloud consola, pode ver cada rastreio que contém o seguinte:

  • Uma vista de nível elevado de um pedido do Cloud Storage de princípio a fim.

  • Vários intervalos, cada intervalo a capturar uma única operação com indicação de data/hora no pedido do Cloud Storage que foi realizado.

Para ler mais acerca dos rastreios e dos intervalos, consulte a documentação do OpenTelemetry sobre rastreios e intervalos.

Preços

Os dados de rastreio são cobrados. As cobranças baseiam-se no número de intervalos de rastreio carregados e analisados pelo Cloud Trace. Para saber mais acerca dos intervalos de rastreio faturáveis e ver exemplos de preços, consulte o artigo Custos do Cloud Trace.

Antes de começar

Antes de poder recolher rastreios para a sua utilização da API Cloud Storage, tem de concluir os seguintes passos:

  1. Instale a biblioteca 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.

    Ative a API

Funções necessárias

Para receber a autorização de que precisa para escrever rastreios no Cloud Trace, peça ao seu administrador para lhe conceder a função de IAM do agente do Cloud Trace (roles/coudtrace.agent) no projeto usado pelo cliente.

Esta função predefinida contém a autorização cloudtrace.traces.patch , que é necessária para escrever rastreios no Cloud Trace.

Também pode obter estas autorizações com funções predefinidas ou criar funções personalizadas para conceder autorizações específicas. Para ver instruções sobre a concessão de funções em projetos, consulte o artigo Conceda ou revogue uma função. Para mais informações sobre a função do agente do Cloud Trace, consulte a documentação do Identity and Access Management (IAM).

Configure o rastreio para a sua aplicação

Use as seguintes instruções para configurar a monitorização e começar a recolher dados de rastreio com a biblioteca cliente do Cloud Storage:

C++

  1. Instale as seguintes versões:

    • Versão v2.16.0 ou posterior da biblioteca cliente de C++

    • Versão 14 ou posterior do C++

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

  3. Crie uma instância do cliente do Cloud Storage com rastreios 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 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 o OpenTelemetry. Também pode usar qualquer exportador à sua escolha.

  3. Instale o propagador do Cloud Trace.

  4. Crie uma instância do cliente do Cloud Storage com rastreios 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 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 pode usar qualquer exportador à sua escolha.

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

  3. Instale a instrumentação de pedidos do OpenTelemetry para rastrear os pedidos HTTP subjacentes.

    pip install opentelemetry-instrumentation-requests

  4. Defina a variável de ambiente para ativar seletivamente a monitorização para o cliente de armazenamento Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configure o exportador de rastreios e o fornecedor de rastreios. 

    
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))

Veja os seus rastreios

Use o explorador do Cloud Trace para ver os dados de rastreio na Google Cloud consola:

  1. Na Google Cloud consola, aceda à página Explorador de rastreios:

    Aceda ao Explorador de rastreios

    Também pode encontrar esta página através da barra de pesquisa.

  2. Na página do Explorador de rastreios, clique num rastreio específico no gráfico de dispersão para ver os detalhes do rastreio.

    O painel Detalhes do rastreio apresenta uma tabela de intervalos de rastreio.

  3. Opcional: clique numa linha de intervalo para ver informações detalhadas sobre um intervalo específico, como as seguintes informações:

    • Atributos: pares de chave-valor que fornecem informações adicionais acerca do intervalo.

    • Registos e eventos: entradas de registo associadas ao intervalo.

    • Rastreios de pilha: rastreios de pilha associados ao intervalo.

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

Para mais informações sobre como usar o explorador do Cloud Trace, consulte o artigo Encontre e explore rastreios.

O que se segue?