Constructs & Workloads¶
synthkit's catalog is a collection of isolated construct and workload modules. As of v1.0.0 there are 42 construct kinds and 2 workload kinds. Each construct is a separate Go package under internal/construct/<kind>/; workloads live under internal/workload/<kind>/. Neither constructs nor workloads import each other or the blueprint package — isolation is enforced by internal/archtest.
Construct granularity principle¶
A construct boundary is drawn at the smallest unit that is independently declarable in a blueprint AND carries a distinct shared identity or cross-construct join — not at the delivery pipeline.
- Distinct fixture + distinct declaration + distinct join → separate construct, sharing a mechanic library.
ec2,rds, andelasticacheare separate because each hangs off its own fixture type (fixture.Node,fixture.DB,fixture.Cache) and joins to other constructs through that identity. - Same pipeline + same identity + declared together → one construct with config-gated sub-families.
cw_infrabundles ALB/NLB/EBS/NAT/EKS/S3/Firehose off one cloud identity, each family gated by a per-family switch.k8s_clustergates OpenCost/Kepler/Alloy viak8s_monitoringconfig. - Engine/type variants of one resource → a config discriminator, not a new kind. RDS Postgres vs Aurora Postgres share the
rdsconstruct; the engine selects the CloudWatch family variant.
For the emission switch that controls which constructs a declaration fans into, see emission-switches.md.
Kubernetes¶
Constructs in this group are substrate-scoped — they carry no blueprint label. The cluster name disambiguates across blueprints.
| Kind | Description | Signal area |
|---|---|---|
k8s_cluster | Core k8s-monitoring substrate: kube-state-metrics, node-exporter, cAdvisor, kubelet. Gates OpenCost/Kepler and the Alloy collector via k8s_monitoring config. | k8s |
k8s_profiling | Pyroscope-based continuous profiling substrate for workloads running in the cluster. | profiles |
ksm_ingress | KSM ingress metrics (kube_ingress_*) with cluster disambiguation. | k8s |
etcd | etcd cluster health and Raft metrics. | k8s-addons |
Kubernetes add-ons¶
Add-ons are declared under cluster.addons in the blueprint. Each is substrate-scoped and emits pod-joined metrics + logs.
| Kind | Description | Signal area |
|---|---|---|
argocd | Argo CD controller and application metrics. | k8s-addons |
cert_manager | cert-manager certificate lifecycle metrics. | k8s-addons |
cluster_autoscaler | Cluster Autoscaler node scaling and utilization metrics. | k8s-addons |
core_dns | CoreDNS request and cache metrics. | k8s-addons |
ebs_csi | AWS EBS CSI driver metrics (volume attach, provision, I/O). | k8s-addons |
envoy_gateway | Envoy Gateway proxy metrics (upstream/downstream request rates, latency). | k8s-addons |
external_dns | ExternalDNS DNS sync and registry metrics. | k8s-addons |
karpenter | Karpenter node provisioner metrics (node lifecycle, disruption, scheduling). | k8s-addons |
load_balancer_controller | AWS Load Balancer Controller metrics. | k8s-addons |
vpc_cni | AWS VPC CNI IP allocation metrics. | k8s-addons |
Alloy health¶
| Kind | Description | Signal area |
|---|---|---|
alloy_health | Grafana Alloy / agent health and pipeline metrics. | fm |
AWS infrastructure (CloudWatch)¶
These constructs are blueprint-scoped (they carry the blueprint selector label). They use internal/cw for the five-stat CloudWatch expansion (_sum/_average/_maximum/_minimum/_sample_count).
| Kind | Description | Signal area | Blueprint declaration |
|---|---|---|---|
ec2 | EC2 instance CloudWatch metrics (aws_ec2_*). Shares fixture.Node identity with the k8s cluster. | cw | Gated by cluster.observability.cloudwatch |
cw_infra | CloudWatch infrastructure families: ALB, NLB, EBS, NAT Gateway, EKS control plane, S3, Kinesis Firehose. Each family is independently gated. | cw | cloud.cloudwatch.* switches |
AWS databases and cache¶
| Kind | Description | Signal area | Blueprint declaration |
|---|---|---|---|
rds | RDS CloudWatch metrics (aws_rds_*). Shares fixture.DB with dbo11y constructs. Supports Postgres, MySQL, Aurora variants. | cw | databases[].observability.cloudwatch |
elasticache | ElastiCache CloudWatch metrics (aws_elasticache_*). | cw | caches[].observability.cloudwatch |
docdb | Amazon DocumentDB CloudWatch metrics (aws_docdb_*). | cw | databases[].engine: documentdb |
neptune | Amazon Neptune CloudWatch metrics (aws_neptune_*). | cw | databases[].engine: neptune |
aoss | Amazon OpenSearch Serverless (AOSS) CloudWatch metrics. | cw | integrations: aoss |
AWS managed services¶
| Kind | Description | Signal area |
|---|---|---|
glue | AWS Glue job and crawler CloudWatch metrics. | cw |
mwaa | Amazon Managed Workflows for Apache Airflow CloudWatch metrics. | cw |
Database Observability (dbo11y)¶
Substrate-scoped. Shares fixture.DB identity with the corresponding CloudWatch construct.
| Kind | Description | Signal area | Blueprint declaration |
|---|---|---|---|
dbo11y_postgres | Grafana Database Observability for PostgreSQL — query digests, connection pool, replication. | dbo11y | databases[].observability.dbo11y: true |
dbo11y_mysql | Grafana Database Observability for MySQL. | dbo11y | databases[].observability.dbo11y: true |
CSP: Azure and GCP¶
Both are substrate-scoped. Sub-families are gated by sub_signals: [...] in the integration declaration (empty/omitted = all emit).
| Kind | Description | Signal area |
|---|---|---|
csp_azure | Grafana CSP Azure integration: VMs, App Service, SQL, Storage, Cosmos DB, Functions, and more. | cspazure |
csp_gcp | Grafana CSP GCP integration: Compute, Cloud SQL, Cloud Storage, Pub/Sub, Cloud Run, BigTable. | cspgcp |
AI & LLM¶
All AI/LLM constructs are blueprint-scoped and tech-generic. gen_ai metrics go via sink/promrw final names; spans via the hand-encoded OTLP seam. The OTel metrics SDK ban applies.
| Kind | Description | Signal area | Blueprint declaration |
|---|---|---|---|
bedrock | Amazon Bedrock CloudWatch model invocation metrics (aws_bedrock_*). | bedrock | integrations: bedrock |
agentcore | AWS Bedrock AgentCore CloudWatch metrics and Loki logs. | agentcore | integrations: agentcore |
portkey_gateway | Portkey AI gateway: request/token/cost metrics scraped from the Portkey API. | portkey | integrations: portkey_gateway |
portkey_poller | Portkey native scrape metrics (the separate Portkey Prometheus exporter path). | portkey | integrations: portkey_poller |
langsmith_eval | LangSmith evaluation metrics: scores, pass rates, latency by evaluator. | langsmith | integrations: langsmith_eval |
langsmith_platform | LangSmith platform-level metrics: run volumes, latency, token counts. | langsmith | integrations: langsmith_platform |
snowflake | Snowflake Cortex usage and query metrics via the Snowflake Grafana integration. | snowflake | integrations: snowflake |
qualification_pipeline | AI qualification pipeline metrics (model evaluation + selection flow). | qualification | integrations: qualification_pipeline |
Network¶
| Kind | Description | Signal area | Blueprint declaration |
|---|---|---|---|
network_topology | SNMP topology exporter metrics: device availability, interface I/O, link state, federation metrics. Mirrors the external network-topology-exporter signal contract. | nettopo | integrations: network_topology |
Hosts¶
| Kind | Description | Signal area | Blueprint declaration |
|---|---|---|---|
host | Bare-metal or VM host metrics (node_exporter-style) for non-k8s hosts. | host | hosts: |
Integrations and Grafana products¶
These constructs model external systems Grafana Cloud ingests, or Grafana Cloud products you have enabled.
| Kind | Description | Signal area | Blueprint section |
|---|---|---|---|
cloudflare | Cloudflare zone metrics via the Grafana Cloudflare integration (blueprint-scoped). | cloudflare | integrations: cloudflare |
beyla_agent | Grafana Beyla eBPF instrumentation — application RED metrics without SDK instrumentation. | beyla | integrations: beyla |
synthetic_monitoring | Grafana Synthetic Monitoring check data: probe results, latency, reachability. | sm | features: synthetic_monitoring |
fleet_management | Grafana Fleet Management collector registration and health. | fm | features: fleet_management |
Workloads¶
Workloads mint request-correlated telemetry. They share the blueprint's ledger for end-to-end correlation IDs. Both workload kinds may coexist in one blueprint.
| Kind | When to use | Description |
|---|---|---|
web_service | A single service | Emits RED metrics, traces (browser → backend → DB hops), optional RUM/Faro beacons, optional gen_ai hops. The simple, common case. |
app | A multi-service graph | A declared graph of typed service nodes (services:), each emitting its own custom metrics/logs/spans via the telemetry DSL. One ledger mint drives one correlated trace across the whole graph. Use when you need per-service incident targeting, per-service scaling, or custom metric families per node. |
The app workload's telemetry DSL supports typed nodes (frontend/web/grpc/worker/job/stream/gateway/db/cache/llm/agent/tool/workflow/retrieval), ValueModel one-of value generators (const, enum, int_range, float_range, normal, shape, ref), and reusable Profile bundles from the catalog in internal/telemetryspec/profiles.
For workload configuration and the telemetry DSL reference, see workloads.md.