Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Prometheus — um servidor, dois destinos de scrape

Este exemplo compila uma stack pequena e real — um servidor de métricas Prometheus a fazer scrape de dois servidores de dashboards do Grafana — a partir de um único Aggregate escrito pelo programador em dois destinos:

  • Docker Compose para o desenvolvimento local, e
  • Kubernetes através da síntese de Workload sobre a imagem oficial prom/prometheus.

O mesmo aggregate.yaml conduz ambos. Só muda, de destino para destino, a camada de Recipe selecionada pelo Manifest.

O Grafana serve as suas próprias métricas no formato de texto do Prometheus em /metrics na sua porta web, e fá-lo por predefinição, pelo que cada Grafana é um destino de scrape real. Ambos são o mesmo tipo de Component ligado duas vezes, pelo que tudo o que difere entre os dois jobs de scrape vem do que é escrito em cada ligação e de onde cada Grafana diz que serve as suas métricas.

Ficheiros

FicheiroPapel
aggregate.yamlIntenção do programador: dois Grafanas, team-dashboards e ops-dashboards (ambos core/observability/grafana), e um servidor metrics (core/observability/prometheus) que declara uma utilização scrape_target de cada um.
manifest-compose.yamlMapeia o tipo Prometheus para a Recipe do Compose (compose/prometheus) e o tipo Grafana para a Recipe do Compose do Grafana (compose/grafana).
manifest-helm-synth.yamlMapeia o tipo Prometheus para a Recipe helm sintetizada (helm/prometheus) e o tipo Grafana para a Recipe helm sintetizada do Grafana (helm/grafana). Nenhuma das duas obtém um chart.
release-compose.yaml / release-helm-synth.yamlDocumentos do operador para os dois destinos.

Ligar dois destinos num socket

scrape_target é um socket que contém duas ligações, e cada ligação torna-se um job de scrape:

metrics:
type: core/observability/prometheus
uses:
scrape_target:
team-dashboards:
target: team-dashboards
ops-dashboards:
target: ops-dashboards
values:
job_name: ops-grafana
scrape_interval: 30s

A ligação team-dashboards não escreve nenhum values, pelo que o seu job usa o que o socket declara. A ligação ops-dashboards define duas chaves, e cada chave que define molda apenas esse job — o job team-dashboards não é tocado por elas.

O destino diz onde serve as métricas

Uma ligação diz com que frequência o Prometheus faz scrape e sob que nome de job; nunca diz onde. Esse é um facto próprio do destino, e é o destino que o publica: cada Recipe do Grafana publica metrics_endpoint, o endereço completo das suas métricas — esquema, host, porta e caminho, como http://team-dashboards:3000/metrics no Compose. O Prometheus constrói o job de scrape a partir desse endereço: o seu esquema, o seu caminho, e o seu host e a sua porta como destino do job.

Assim, um destino que não serve métricas não publica nenhum endereço, e ligá-lo a scrape_target interrompe a compilação, nomeando-o, em vez de compilar um job que não faria scrape de nada. Um produto cujas métricas estão desativadas até que um valor as ative — muitos no catálogo aceitam metrics_enabled — publica o seu endereço enquanto estão ativadas. No Kubernetes, um destino pode, em alternativa, publicar aquilo através do qual o Prometheus descobre as suas métricas, um Service ou um seletor de pods, quando nenhum endereço único as alcança a todas; a realização do Compose não tem nenhum cluster em que fazer essa descoberta e é interrompida perante um destino desses.

O socket admite igualmente servidores, servidores com estado e workers, pelo que uma base de dados, um repositório de registos ou um operador se liga da mesma forma; se pode ser alvo de scrape é decidido por aquilo que publica.

O que demonstra

  • Uma única superfície de autoria, muitos destinos. Um único Aggregate é a fonte de verdade sobre o que a stack é. Cada Manifest diz como realizá-la.
  • Um socket, muitas ligações. O Prometheus faz scrape de tantos destinos quantos o Aggregate ligar a scrape_target. A Recipe emite um job de scrape por ligação, pelo que o número de jobs segue a topologia e não a Recipe.
  • Configuração por ligação. job_name e scrape_interval são declarados no valueSchema do socket, o que os torna propriedades de uma ligação e não do servidor. Um único Prometheus a fazer scrape de vários destinos não consegue exprimir várias cadências num único valor válido para todo o Component.
  • Os valores predefinidos declarados preenchem as chaves que uma ligação omite. scrape_interval tem um valor predefinido no valueSchema do socket. Uma ligação que o omite — aqui team-dashboards — recebe-o, e uma ligação que o define — ops-dashboards — substitui apenas o que definiu.
  • Ligação do scrape através da String Pipe. O metrics_endpoint de cada Recipe do Grafana é canalizado para o Prometheus e renderizado no job desse Grafana: o seu esquema, o seu caminho e a sua entrada targets. O compilador encaminha a string sem a interpretar: cada Recipe decide que endereço o seu próprio destino publica, e o compilador canaliza-o sem alterações.
  • Configuração idiomática para o Provider. Nos dois destinos, o servidor escreve no arranque um prometheus.yml mínimo cujos jobs de scrape endereçam os Grafanas ligados e, em seguida, executa o Prometheus com ele. No Compose, isto corre como um serviço; no Kubernetes, o mesmo contentor é renderizado num StatefulSet.
  • Estado persistente. O Prometheus guarda as suas amostras num volume de dados para que sobrevivam a reinícios — um volume do Compose com nome localmente, e um PersistentVolumeClaim por réplica dimensionado a partir de infra.storage no Kubernetes. Cada Grafana mantém os seus utilizadores e dashboards num volume próprio.
  • Imagens reprodutíveis. Cada Recipe aqui fixa a tag da sua imagem a partir de infra.engine_version, pelo que as cargas de trabalho renderizadas referenciam imagens fixas.
  • Estrutura enxuta de finalidade única. No Kubernetes, o componente Prometheus é renderizado como o seu StatefulSet, os seus Services ClusterIP e Headless e o seu pedido de volume de dados — nada mais. Cada Grafana é renderizado como o seu próprio Deployment, o seu Service e o seu pedido de volume de dados.

Gerar o exemplo

É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.

Escreva o exemplo numa nova pasta com o nome dele:

Terminal window
aggrega scaffold --example prometheus-scrape

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd prometheus-scrape

Compilação

Este espaço de trabalho não inclui nenhum .aggrega-config.yaml, pelo que as entidades da biblioteca standard são resolvidas a partir do registo do hub, hub.aggrega.ai, e não é necessária nenhuma flag de catálogo:

Terminal window
# Local development (Docker Compose)
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (Workload synthesis on prom/prometheus)
aggrega build --release release-helm-synth.yaml --auto-pull

Os artefactos renderizados ficam em dist/. --auto-pull resolve as dependências de cada Release no seu ficheiro de bloqueio durante a compilação; executar aggrega pull --release release-compose.yaml uma vez à partida faz o mesmo e permite que as compilações seguintes corram sem a flag. O destino sintetizado não precisa de obter nenhum chart externo — as duas Recipes renderizam as imagens oficiais diretamente em recursos do Kubernetes.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa própria. Se a pasta Workspace ainda não contiver uma pasta `prometheus-scrape`, chame uma vez a ferramenta `scaffold` com `example` definido como `prometheus-scrape` e sem `dir`: esta escreve o exemplo numa nova pasta `prometheus-scrape`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-compose.yaml` e `release-helm-synth.yaml` — de cada vez com `workspace_root` definido como `prometheus-scrape`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada compilação escreveu; encontram-se em `prometheus-scrape/dist/`.

Como é a configuração de scrape compilada

No Compose, o servidor escreve um prometheus.yml com um job por cada Grafana ligado, cada um a endereçar o metrics_endpoint que esse Grafana publica — o nome do seu serviço compose e a sua porta:

scrape_configs:
- job_name: ops-grafana
scrape_interval: 30s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "ops-dashboards:3001"
- job_name: team-dashboards
scrape_interval: 15s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "team-dashboards:3000"

No Kubernetes, os mesmos dois jobs são escritos pelo comando de arranque do StatefulSet sintetizado, cada um a endereçar o Service desse Grafana, que o fornecedor helm nomeia a partir do componente e da sua chave de serviço default:

scrape_configs:
- job_name: ops-grafana
scrape_interval: 30s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "ops-dashboards-default:3001"
- job_name: team-dashboards
scrape_interval: 15s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "team-dashboards-default:3000"

Os dois destinos compilam os mesmos dois jobs a partir das mesmas duas arestas do Aggregate: o metrics_endpoint de cada Grafana viaja pela sua própria ligação scrape_target, e o compilador canaliza essa string para o job sem a interpretar. O que difere entre os destinos é o endereço que cada Grafana publica — um nome de serviço compose num, um nome de Service no outro — e a carga de trabalho em que a configuração é escrita — um serviço do Compose num, um StatefulSet no outro. Aqui, os dois Grafanas estão no mesmo âmbito que o Prometheus; no Kubernetes, um Grafana que a Release coloca noutro namespace é endereçado pelo nome do seu Service qualificado com esse namespace.

Leia-se o job team-dashboards lado a lado com o job ops-grafana para ver de onde vem cada valor. O job ops-grafana tem ops-grafana e 30s porque a sua ligação escreve ambos. O job team-dashboards tem team-dashboards como o seu job_name porque o Aggregate não declara nenhum e a Recipe recorre ao alias da ligação — o nome que este Aggregate deu à ligação — e tem 15s porque esse é o valor predefinido que o socket scrape_target do Component declara para a chave que essa ligação omitiu. O esquema, o metrics_path e o destino dos dois jobs vêm do endereço que cada Grafana publica, que é onde o Grafana serve as suas métricas, pelo que nenhuma das duas ligações diz nada sobre eles. Definir uma chave numa ligação substitui-a para esse job e deixa o outro job intacto.

Tudo isto acontece do lado consumidor. A configuração por ligação surge apenas no contexto de renderização do nó que escreveu a ligação, nunca no do destino, pelo que ligar ou ajustar uma ligação a um Grafana nunca perturba aquilo que esse Grafana renderiza por si — o seu Deployment e o seu Service são os mesmos bytes em qualquer dos casos.

O Grafana entrega as suas métricas a qualquer chamador, pelo que nenhuma das duas ligações tem uma credencial. Para um destino cujas métricas exigem uma, a ligação transporta-a na sua ranhura credential, e o Prometheus apresenta-a como um bearer token lido de um ficheiro; um destino que publica metrics_credential_required como true interrompe a compilação enquanto a sua ligação não tiver nenhuma.

Executá-lo (Compose)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker compose -f dist/app/compose/docker-compose.yaml up -d

A Release dá a cada Grafana a sua própria porta — team-dashboards na 3000 e ops-dashboards na 3001 — para que os dois corram lado a lado localmente. Cada Grafana escuta na porta que a sua Release lhe dá, e cada porta viaja no endereço que esse Grafana publica no destino do seu próprio job de scrape.

Abra http://127.0.0.1:9090 — o navegador de expressões do Prometheus, que a Recipe do Compose publica apenas no endereço de loopback do host. Em Status → Targets, os dois jobs são listados com os nomes que a configuração compilada lhes dá, ops-grafana e team-dashboards, cada um a endereçar o /metrics do seu Grafana. Uma consulta por grafana_build_info, o gauge que cada Grafana define como 1 e etiqueta com a sua versão, devolve uma série por job. Para desmontar, use docker compose -f dist/app/compose/docker-compose.yaml down.