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
| Ficheiro | Papel |
|---|---|
aggregate.yaml | Intençã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.yaml | Mapeia 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.yaml | Mapeia 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.yaml | Documentos 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: 30sA 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_nameescrape_intervalsão declarados novalueSchemado 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_intervaltem um valor predefinido novalueSchemado socket. Uma ligação que o omite — aquiteam-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_endpointde cada Recipe do Grafana é canalizado para o Prometheus e renderizado no job desse Grafana: o seu esquema, o seu caminho e a sua entradatargets. 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.ymlmí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.storageno 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:
aggrega scaffold --example prometheus-scrapeDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd prometheus-scrapeCompilaçã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:
# 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-pullOs 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)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dA 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.