Escrever métricas OTLP usando um arquivo secundário do OpenTelemetry

Neste tutorial, mostramos como gravar, implantar e chamar um serviço do Cloud Run que informa métricas OTLP personalizadas para o Serviço gerenciado do Google Cloud para Prometheus usando o arquivo secundário do OpenTelemetry.

Se você tiver um serviço do Cloud Run que informe métricas do Prometheus, use o arquivo secundário do Prometheus para o Cloud Run.

Objetivos

Grave, crie e implante um serviço no Cloud Run com o arquivo secundário do OpenTelemetry.
Gere métricas personalizadas e informe-as ao Google Cloud Managed Service For Prometheus.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Acessar o seletor de projetos

Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Acessar o seletor de projetos

Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

Ative as APIs Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build .
Ative as APIs

Instale e inicialize a CLI gcloud.
Atualize a Google Cloud CLI: gcloud components update

Funções exigidas

Para conseguir as permissões necessárias para concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

Editor do Cloud Build (roles/cloudbuild.builds.editor)
Administrador do Cloud Run (roles/run.admin)
Criar contas de serviço (roles/iam.serviceAccountCreator)
Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
Gravador de métricas do Monitoring ()roles/monitoring.metricWriter
Usuário da conta de serviço (roles/iam.serviceAccountUser)
Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
Administrador de armazenamento (roles/storage.admin)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Observe também que a conta de serviço do Cloud Run precisa do papel de Gravador da métrica de monitoramento (roles/monitoring.metricWriter). A conta de serviço padrão do Compute Engine tem esse papel por padrão, mas talvez seja necessário adicioná-la se você tiver alterado as permissões ou estiver usando uma conta de serviço diferente.

Como configurar padrões do gcloud

Para configurar a gcloud com os padrões do serviço do Cloud Run, realize as etapas a seguir:

Defina seu projeto padrão:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto que você criou para este tutorial.
Configure a gcloud para a região escolhida:
```
gcloud config set run/region REGION
```
Substitua REGION pela região compatível do Cloud Run.

Locais do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa seus serviços do Cloud Run está localizada em uma região específica e é gerenciada pelo Google para estar disponível de maneira redundante em todas as zonas da região.

Atender aos seus requisitos de latência, disponibilidade ou durabilidade são os principais fatores para selecionar a região em que seus serviços do Cloud Run são executados. Geralmente, é possível selecionar a região mais próxima de seus usuários, mas considere a localização dos outros produtos do Google Cloud usados pelo serviço do Cloud Run. O uso de produtos do Google Cloud em vários locais pode afetar a latência e o custo do serviço.

O Cloud Run está disponível nas regiões a seguir:

Sujeitas aos preços do nível 1

asia-east1 (Taiwan)
asia-northeast1 (Tóquio)
asia-northeast2 (Osaka)
europe-north1 (Finlândia) Baixo CO₂
europe-southwest1 (Madrid)
europe-west1 (Bélgica) Baixo CO_₂
europe-west4 (Países Baixos)
europe-west8 (Milão)
europe-west9 (Paris) Baixo CO₂
me-west1 (Tel Aviv)
us-central1 (Iowa) Baixo CO₂
us-east1 (Carolina do Sul)
us-east4 (Norte da Virgínia)
us-east5 (Columbus)
us-south1 (Dallas)
us-west1 (Oregon) Baixo CO₂

Sujeitas aos preços do nível 2

africa-south1 (Johannesburgo)
asia-east2 (Hong Kong)
asia-northeast3 (Seul, Coreia do Sul)
asia-southeast1 (Singapura)
asia-southeast2 (Jacarta)
asia-south1 (Mumbai, Índia)
asia-south2 (Déli, Índia)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsóvia, Polônia)
europe-west10 (Berlim)
europe-west12 (Turim)
europe-west2 (Londres, Reino Unido) Baixo CO₂
europe-west3 (Frankfurt, Alemanha) Baixo CO₂
europe-west6 (Zurique, Suíça) Baixo CO₂
me-central1 (Doha)
me-central2 (Damã)
northamerica-northeast1 (Montreal) Baixo CO₂
northamerica-northeast2 (Toronto) Baixo CO₂
southamerica-east1 (São Paulo, Brasil) Baixo CO₂
southamerica-west1 (Santiago, Chile) Baixo CO₂
us-west2 (Los Angeles)
us-west3 (Salt Lake City)
us-west4 (Las Vegas)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no console do Google Cloud.

Como criar um repositório de imagens do Artifact Registry

Crie um repositório do Artifact Registry no Docker para hospedar a imagem de serviço de amostra:

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

Substitua:

PROJECT_ID pelo nome do projeto que você criou para este tutorial.
Substitua REGION REGION pela região compatível do Cloud Run.

Como recuperar o exemplo de código

Para recuperar o exemplo de código para uso, siga estas etapas:

Clone o repositório do app de amostra na máquina local:
Go
```
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
```
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Mude para o diretório que contém o código de amostra do Cloud Run:
Go
```
cd golang-samples/run/custom-metrics/
```

Como revisar o código

O código deste tutorial consiste nisto:

Um servidor que processa solicitações de entrada e gera uma métrica chamada sample_sidecar_counter.

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
	"go.opentelemetry.io/otel/metric"
	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

var counter metric.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}

Um Dockerfile que define o ambiente operacional do serviço.

FROM golang:1.21 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

A amostra também inclui arquivos no subdiretório collector para criar um coletor OpenTelemetry personalizado:

Um arquivo de configuração para o coletor do OpenTelemetry.

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # automatically detect Cloud Run resource metadata
  resourcedetection:
    detectors: [env, gcp]
    timeout: 2s
    override: false

  resource:
    attributes:
      # add instance_id as a resource attribute
    - key: service.instance.id
      from_attribute: faas.id
      action: upsert
      # parse service name from K_SERVICE Cloud Run variable
    - key: service.name
      value: ${env:K_SERVICE}
      action: insert

exporters:
  googlemanagedprometheus: # Note: this is intentionally left blank

extensions:
  health_check:

service:
  extensions: [health_check]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch, memory_limiter, resourcedetection, resource]
      exporters: [googlemanagedprometheus]

Um Dockerfile que agrupa a configuração fornecida em uma imagem do coletor upstream.

FROM otel/opentelemetry-collector-contrib:0.75.0

COPY collector-config.yaml /etc/otelcol-contrib/config.yaml

Como enviar o código

O código de envio consiste em três etapas: criar uma imagem de contêiner com o Cloud Build, fazer upload da imagem de contêiner no Container Artifact e implantar a imagem de contêiner no Cloud Run.

Para enviar o código, siga estas etapas:

Crie o contêiner de serviço de amostra e publique no Container Artifact:
```
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
```
Após a conclusão, você verá uma mensagem de "SUCESSO" contendo o ID, a hora da criação e o nome da imagem. A imagem é armazenada no Artifact Registry e poderá ser reutilizada se você quiser.
Compile seu contêiner e publique no Container Artifact:
```
gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
```
Após a conclusão, você verá uma mensagem de "SUCESSO" contendo o ID, a hora da criação e o nome da imagem. A imagem é armazenada no Artifact Registry e poderá ser reutilizada se você quiser.

Implante sua aplicação:

YAML

Crie um novo arquivo chamado service.yaml com o seguinte conteúdo:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE-NAME
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/container-dependencies: "{app:[collector]}"
    spec:
      containers:
      - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
        name: app
        ports:
        - containerPort: CONTAINER_PORT
        env:
        - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
          value: "http://localhost:4317"
      - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
        name: collector
        startupProbe:
          httpGet:
            path: /
            port: 13133

Substitua:
- CONTAINER_PORT pela porta que o contêiner de entrada do serviço detecta. Por padrão, ele é 8080.
- SERVICE-NAME por qualquer nome para seu serviço, como custom-metrics-sample-service.

Crie o serviço com o seguinte comando:
```
gcloud run services replace service.yaml
```
Esse comando retorna um URL de serviço. Use esse URL para testar o aplicativo de amostra em Como testar.

Testar

Usando o URL do comando gcloud run em Como enviar o código, conecte-se ao serviço para gerar algumas métricas de amostra. É possível executar esse comando várias vezes para gerar dados mais interessantes.

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

Substitua SERVICE_URL pelo URL da função.

Em seguida, navegue até o Metrics Explorer na seção do Cloud Monitoring do Console do Google Cloud e selecione a métrica sidecar_sample_counter.

Métrica personalizada exibida na interface do Metrics Explorer

Também é possível consultar as métricas com o PromQL. Por exemplo, a consulta abaixo filtrará as métricas com base no ID da instância do Cloud Run:

sidecar_sample_counter{instance="INSTANCE_ID"}

Substitua INSTANCE_ID pelo ID de qualquer instância do serviço (disponível nos registros da instância ou no servidor de metadados).

Esta consulta produz um gráfico como este:

Métrica personalizada consultada pelo PromQL

Limpeza

Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto atual e quer mantê-lo sem as alterações incluídas neste tutorial, exclua os recursos criados para o tutorial.

Como excluir o projeto

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

Cuidado: excluir um projeto tem os seguintes efeitos:

Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

No Console do Google Cloud, acesse a página Gerenciar recursos.
Acessar "Gerenciar recursos"
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Como excluir recursos do tutorial

Exclua o serviço do Cloud Run que você implantou neste tutorial:
```
gcloud run services delete SERVICE-NAME
```
SERVICE-NAME é o nome escolhido do serviço.

Também é possível excluir os serviços do Cloud Run no Console do Google Cloud.
Remova a configuração da região padrão da gcloud que você adicionou durante a configuração do tutorial:
```
 gcloud config unset run/region
```
Remova a configuração do projeto:
```
 gcloud config unset project
```
Exclua outros recursos do Google Cloud criados neste tutorial:
- Excluir o repositório do Docker do Artifact Registry

A seguir

Mais exemplos, incluindo exemplos de traces e registros, estão disponíveis no GitHub.