Prometheus — um servidor, dois destinos de scrape
Este exemplo compila um stack pequeno e real — um servidor de métricas Prometheus fazendo scrape de dois servidores de dashboards do Grafana — a partir de um único Aggregate escrito pelo desenvolvedor para dois destinos:
- Docker Compose para o desenvolvimento local, e
- Kubernetes por meio da síntese de Workload sobre a imagem oficial
prom/prometheus.
O mesmo aggregate.yaml conduz ambos. Só muda por 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 faz isso por padrão, então cada Grafana é um destino de scrape real. Ambos são o mesmo tipo de Component conectado duas vezes, então tudo o que difere entre os dois jobs de scrape vem do que é escrito em cada conexão e de onde cada Grafana diz que serve as suas métricas.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: dois Grafanas, team-dashboards e ops-dashboards (ambos core/observability/grafana), e um servidor metrics (core/observability/prometheus) que declara um uso 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 busca um chart. |
release-compose.yaml / release-helm-synth.yaml | Documentos do operador para os dois destinos. |
Conectando dois destinos em um socket
scrape_target é um socket que traz duas conexões, e cada conexão se torna 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 conexão team-dashboards não escreve nenhum values, então o seu job usa o que o socket declara. A conexão ops-dashboards define duas chaves, e cada chave que ela define molda apenas esse job — o job team-dashboards não é tocado por elas.
O destino diz onde serve as métricas
Uma conexão diz com que frequência o Prometheus faz scrape e sob qual nome de job; ela nunca diz onde. Esse é um dado 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 conectá-lo a scrape_target interrompe o build, nomeando-o, em vez de compilar um job que não faria scrape de nada. Um produto cujas métricas ficam desativadas até que um valor as ative — muitos no catálogo aceitam metrics_enabled — publica o seu endereço enquanto elas estão ativadas. No Kubernetes, um destino pode, em vez disso, publicar aquilo por meio do qual o Prometheus descobre as suas métricas, um Service ou um seletor de pods, quando nenhum endereço único alcança todas elas; a realização do Compose não tem nenhum cluster em que fazer essa descoberta e é interrompida diante de um destino assim.
O socket admite servidores, servidores com estado e workers da mesma forma, então um banco de dados, um repositório de logs ou um operador é conectado do mesmo jeito; se ele pode ser alvo de scrape é decidido pelo que ele publica.
O que ele demonstra
- Uma única superfície de autoria, muitos destinos. Um único Aggregate é a fonte da verdade sobre o que o stack é. Cada Manifest diz como realizá-lo.
- Um socket, muitas conexões. O Prometheus faz scrape de tantos destinos quantos o Aggregate conectar a
scrape_target. A Recipe emite um job de scrape por conexão, então o número de jobs segue a topologia, e não a Recipe. - Configuração por conexão.
job_nameescrape_intervalsão declarados novalueSchemado socket, o que os torna propriedades de uma conexão, e não do servidor. Um único Prometheus que faz scrape de vários destinos não consegue expressar várias cadências em um único valor para todo o Component. - Valores padrão declarados preenchem as chaves que uma conexão omite.
scrape_intervaltraz um valor padrão novalueSchemado socket. Uma conexão que o omite — aquiteam-dashboards— o recebe, e uma conexão que o define —ops-dashboards— sobrescreve apenas o que definiu. - Conexão do scrape pela String Pipe. O
metrics_endpointde cada Recipe do Grafana é canalizado para o Prometheus e renderizado no job daquele Grafana: o seu esquema, o seu caminho e a sua entradatargets. O compilador roteia a string sem interpretá-la: cada Recipe decide qual endereço o seu próprio destino publica, e o compilador o canaliza sem alterações. - Configuração idiomática para o Provider. Nos dois destinos, o servidor escreve na inicialização um
prometheus.ymlmínimo cujos jobs de scrape endereçam os Grafanas conectados e depois executa o Prometheus com ele. No Compose isso roda como um serviço; no Kubernetes o mesmo contêiner é renderizado em um StatefulSet. - Estado persistente. O Prometheus armazena as suas amostras em um volume de dados para que sobrevivam a reinicializações — um volume nomeado do Compose localmente e um PersistentVolumeClaim por réplica dimensionado a partir de
infra.storageno Kubernetes. Cada Grafana mantém os seus usuários e dashboards em um volume próprio. - Imagens reproduzíveis. Cada Recipe aqui fixa a tag da sua imagem a partir de
infra.engine_version, então as cargas de trabalho renderizadas referenciam imagens fixas. - Estrutura enxuta de propósito único. No Kubernetes, o componente Prometheus é renderizado como o seu StatefulSet, os seus Services ClusterIP e Headless e a sua solicitação de volume de dados — nada mais. Cada Grafana é renderizado como o seu próprio Deployment, o seu Service e a sua solicitação de volume de dados.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example prometheus-scrapeEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd prometheus-scrapeBuild
Este espaço de trabalho não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária:
# 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 artefatos renderizados ficam em dist/. --auto-pull resolve as dependências de cada Release no seu arquivo de bloqueio durante o build; executar aggrega pull --release release-compose.yaml uma vez no início faz o mesmo e permite que builds posteriores rodem sem a flag. O destino sintetizado não precisa buscar 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 este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta 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`: ela grava o exemplo em uma nova pasta `prometheus-scrape`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-compose.yaml` e `release-helm-synth.yaml` — cada vez com `workspace_root` definido como `prometheus-scrape`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `prometheus-scrape/dist/`.Como é a configuração de scrape compilada
No Compose, o servidor escreve um prometheus.yml com um job por Grafana conectado, cada um endereçando o metrics_endpoint que aquele 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 inicialização do StatefulSet sintetizado, cada um endereçando o Service daquele Grafana, que o provedor helm nomeia com base no componente e na 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 conexão scrape_target, e o compilador canaliza essa string para o job sem interpretá-la. O que difere entre os destinos é o endereço que cada Grafana publica — um nome de serviço compose em um, um nome de Service no outro — e a carga de trabalho em que a configuração é escrita — um serviço do Compose em um, um StatefulSet no outro. Aqui os dois Grafanas ficam no mesmo escopo que o Prometheus; no Kubernetes, um Grafana que a Release coloca em outro namespace é endereçado pelo nome do seu Service qualificado com esse namespace.
Leia o job team-dashboards lado a lado com o job ops-grafana para ver de onde vem cada valor. O job ops-grafana traz ops-grafana e 30s porque a sua conexão escreve ambos. O job team-dashboards traz team-dashboards como o seu job_name porque o Aggregate não declara nenhum e a Recipe recorre ao alias da conexão — o nome que este Aggregate deu à conexão — e traz 15s porque esse é o valor padrão que o socket scrape_target do Component declara para a chave que aquela conexã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, então nenhuma das duas conexões diz nada sobre eles. Definir uma chave em uma conexão a sobrescreve para aquele job e deixa o outro job intacto.
Tudo isso acontece no lado consumidor. A configuração por conexão aparece apenas no contexto de renderização do nó que escreveu a conexão, nunca no do destino, então conectar ou ajustar uma conexão para um Grafana nunca perturba o que esse Grafana renderiza por si mesmo — o seu Deployment e o seu Service são os mesmos bytes em qualquer caso.
O Grafana entrega as suas métricas a qualquer chamador, então nenhuma das duas conexões traz uma credencial. Para um destino cujas métricas exigem uma, a conexão a traz no seu slot credential, e o Prometheus a apresenta como um bearer token lido de um arquivo; um destino que publica metrics_credential_required como true interrompe o build enquanto a sua conexão não trouxer 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 rodem lado a lado localmente. Cada Grafana escuta na porta que a sua Release lhe dá, e cada porta viaja no endereço que aquele 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 aparecem com os nomes que a configuração compilada lhes dá, ops-grafana e team-dashboards, cada um endereçando o /metrics do seu Grafana. Uma consulta por grafana_build_info, o gauge que cada Grafana define como 1 e rotula com a sua versão, retorna uma série por job. Para desmontar, use docker compose -f dist/app/compose/docker-compose.yaml down.