Constructs & Workloads¶

synthkit's catalog is a collection of isolated construct and workload modules. The current catalog has 50 construct kinds and 3 workload kinds (53 total). 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, and elasticache are 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_infra bundles ALB/NLB/EBS/NAT/EKS/S3/Firehose off one cloud identity, each family gated by a per-family switch. k8s_cluster gates OpenCost/Kepler/Alloy via k8s_monitoring config.
• Engine/type variants of one resource → a config discriminator, not a new kind. RDS Postgres vs Aurora Postgres share the rds construct; 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.

Kubernetes add-ons¶

Add-ons are declared under cluster.addons in the blueprint. Each is substrate-scoped and emits pod-joined metrics + logs.

Alloy health¶

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).

AWS databases and cache¶

AWS managed services¶

The five captured-service consumers have conservative one-declaration-per-blueprint/account/ region/kind admission. See authoring and explicit model assumptions and the canonical emitted subset. ESM/fair/info families remain withheld. Redshift user-query/NodeID/managed-storage expansions and Logs by-data-source and other delivery selectors/profiles are withheld. Optional group-owned subscription_filters use literal Lambda/P21 only and four required independent period values; bytes are already compressed. No compression, retry/loss, intake relationship, pipeline or cross-service join is inferred.

Declared pipelines¶

A batch pipeline is declared once, under the environment's cloud.pipelines:, and drives every construct that executes or orchestrates one of its stages from one deterministic run timeline (the shared internal/pipelinerun mechanic). It adds no metric names of its own: each construct maps the timeline onto its existing CloudWatch families.

cloud:
  mwaa: { environments: [etl-airflow] }
  glue: { jobs: [] }
  pipelines:
    - name: orders_daily
      environment: etl-airflow    # the MWAA environment orchestrating it; omit if none
      every: 24h                  # cadence, 1m to 168h
      offset: 2h                  # trigger phase inside every; omit for a seed-derived phase
      stages:
        - { name: extract,   service: glue,    resource: orders-extract,   duration: 12m }
        - { name: transform, service: glue,    resource: orders-transform, duration: 20m }
        - { name: publish,   service: airflow,                             duration: 2m }

• Pipeline names are unique across the whole blueprint, including different environments and pipelines with disjoint stage names. The loader rejects repeats with both owning environment names; rename the pipeline declaration, not its CloudWatch dimensions. Pipeline and stage names match [a-z0-9_-]+; the canonical incident target remains <pipeline>.<stage>. Environment names are not delimiter-restricted, so they are not concatenated into stage targets.
• Run k triggers at k × every + offset, anchored on the Unix epoch. Each stage takes its duration with a ±15% per-run jitter. The resolver supplies the same environment-scoped seed (<blueprint>:<environment>) to Glue and MWAA; phase, duration and failure draws additionally include the pipeline name. Named identity, not declaration order, determines the timeline. Existing single-environment targets and nonpipeline output are unchanged.
• glue: every glue-stage resource is emitted as a job (added to jobs). Its run-time aggregates and executor gauges follow the stage's execution time in each window and read zero between runs. Jobs that are not stages keep their usual values.
• mwaa: for the environment named by environment, queued_tasks and running_tasks (both namespaces) count the pipeline's waiting and executing stages, and aws_mwaa_approximate_age_of_oldest_task is the oldest wait. The environment must be listed in mwaa.environments. Declared pipelines also supply sparse AmazonMWAA DAG outcome timers: aws_amazonmwaa_dagduration_success_* and aws_amazonmwaa_dagduration_failed_* carry dimension_DAG=<pipeline-name>. Their five statistics describe actual trigger-to-terminal durations in milliseconds, including waits, with sample count equal to matching completions. aws_amazonmwaa_task_instance_failures_* aggregates failed stages across the environment with literal dimension_DAG=All and dimension_Task=All; it does not invent per-task failure dimensions. No matching outcome means no observation (all five series absent), even after an earlier nonempty window. Remote-write and native OTLP share this behavior. Environments without a pipeline retain their old output. See the MWAA contract in the CloudWatch signal catalogue.
• A glue stage needs a cloud.glue block and an environment needs a cloud.mwaa block; the loader rejects either missing.
• lambda, sqs and redshift stages are accepted and take part in the timeline, but have no emitting pipeline adapters. The independent cloud.lambda and cloud.sqs consumers do not consume that timeline; positive Redshift source observations do not install a consumer.
• Stages are failure targets: see Incidents.

Database Observability (dbo11y)¶

Substrate-scoped. Shares fixture.DB identity with the corresponding CloudWatch construct.

Both accept the database declaration's optional resource: binding to a dependency or pool, with the CloudWatch lane still required. Independently compiled causal models use the same master clock; no shared mutable construct state or special scheduler is involved. The trailing-minute mean latency scales statement-seconds increments and existing synthetic query/wait durations in both metric and log output. Pool mean busy connections match the CloudWatch connection reading; dependency-only bindings keep baseline connections. This does not attribute acquisition wait to a server Lock/IO category or invent SQL errors. MySQL running threads and server maximum connections remain baseline. Bound instances ignore legacy database-axis modes; unbound output is unchanged. See database bindings and bound incidents. DocumentDB/Neptune dbo11y remains unsupported.

CSP: Azure and GCP¶

Both are substrate-scoped. Sub-families are gated by sub_signals: [...] in the integration declaration (empty/omitted = all emit).

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.

Network¶

Hosts¶

Integrations and Grafana products¶

These constructs model external systems Grafana Cloud ingests, or Grafana Cloud products you have enabled.

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.

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.