Esta página foi traduzida pela API Cloud Translation.

Usar rastros do lado do cliente

Esta página descreve como ativar os rastros 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 rastreamento usando as seguintes bibliotecas de cliente do Cloud Storage com suporte:

Visão geral

Ativar os rastros nas bibliotecas de cliente do Cloud Storage permite monitorar o desempenho, identificar problemas de latência e realizar a depuração rapidamente para solicitações do Cloud Storage. Os rastros mostram 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 rastro é composto por 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 trace oferecem os seguintes benefícios ao aplicativo:

Visibilidade de desempenho aprimorada: como os dados de rastreamento são gerados em quase tempo real à medida que o Cloud Storage conclui cada solicitação, é possível identificar rapidamente gargalos na performance e detectar problemas de latência.
Gerenciamento de erros: é possível identificar onde os problemas surgem, agilizando 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 rastreamento.

Como os rastros do cliente funcionam

As seções a seguir explicam em detalhes como a coleta de rastros funciona.

Como a coleta de rastros 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:

Fornecedor 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 rastros 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 rastreamento, consulte Como os exportadores de rastreamento funcionam.

Como os exportadores de rastreamento funcionam

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

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

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

Visualização de alto nível de uma solicitação do Cloud Storage
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 rastros e intervalos, consulte a documentação do OpenTelemetry sobre rastros 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 os intervalos de rastreamento cobráveis e exemplos de preços, consulte Custos do Cloud Trace.

Antes de começar

Antes de coletar rastros para o uso da API Cloud Storage, você precisa concluir as etapas a seguir:

Instale a biblioteca de cliente do Cloud Storage.
Configure a autenticação.
Enable the Cloud Trace API.
Enable the API
Ative a API Cloud Storage.

Ativar a API

Funções exigidas

Para receber a permissão necessária para gravar rastros 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 rastros no Cloud Trace.

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

Configurar o rastreamento para seu app

Use as instruções a seguir para configurar o rastreamento e começar a coletar dados de rastreamento usando a biblioteca de cliente do Cloud Storage:

Java

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
Instale o exportador do Cloud Trace para o OpenTelemetry. Você também pode usar qualquer exportador de sua escolha.
Instale o propagador do Cloud Trace.

Crie uma instância do cliente do Cloud Storage com os rastros 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

Instale a biblioteca de cliente do Python do Cloud Storage:
```
pip install google-cloud-storage[tracing]>=2.18.0
```
Instale o exportador e o propagador do Cloud Trace. Você também pode usar qualquer exportador de sua preferência.
```
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
```
Instale a instrumentação de solicitações do OpenTelemetry para rastrear as solicitações HTTP subjacentes.
```
pip install opentelemetry-instrumentation-requests
```
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
```

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

No console do 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.
Na página Trace Explorer, clique em um trace específico no gráfico de dispersão para conferir os detalhes dele.

O painel Detalhes do trace mostra uma tabela de períodos de trace.
Opcional: clique em uma linha de período para conferir informações detalhadas sobre um período específico, como as seguintes:
- Atributos: pares de chave-valor que fornecem informações adicionais sobre a extensão.
- 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 à extensão.

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