Appendix

Every workload type, fault kind, guard policy, AWS limit, environment variable and CLI flag, in one place.

Reference tables that would clutter a chapter. Everything here was generated from the live registries or read from the code, not typed out by hand.

The workload and fault tables came from:

from proteus.web.catalog_view import build_catalog
catalog = build_catalog()
len(catalog["archetypes"]), len(catalog["profiles"]), len(catalog["faults"])
# (12, 56, 14)

That is the same call the GUI palette makes, so these tables and the palette cannot disagree.

Workload types#

68 in total, from two layers.

Archetypes — 12#

Hand-written, with bespoke internal behavior: a Kafka consumer's lag responds to its producer's rate, a noisy neighbor hurts its victim more than itself. The metrics count is measured, not declared — each generator is asked for representative ticks and the distinct metric names are counted. Same for signals: an archetype claims a signal only if its generator really yielded a record for it.

Archetypes publish into the custom namespace proteus/{model-name} and carry their AWS counterpart in attributes. The AWS namespaces column lists the namespaces their metrics are mapped onto, where a mapping is confirmed.

180 distinct metric names across the twelve, of which 45 carry a confirmed AWS counterpart through proteus.aws_metric and proteus.aws_namespace attributes.

browser-rum is the only archetype that emits RUM and the only one that does not emit traces. It is also the only one whose runtime is browser.

A thirteenth archetype, custom, exists in the schema but is not a workload — it is the delegation mechanism that renders whichever profile a service's kind names. It is deliberately absent from the palette, because probing it with no kind yields a tile with no metrics and no signals, which looks broken.

Profiles — 56#

Declarative. Each covers one distinct AWS namespace, and adding an AWS service is a data edit rather than new code. 393 metric specifications across the 56.

20 of the 393 specs name no AWS counterpart. That null is load-bearing, not an oversight: an invented AWS metric name reads as authoritative and sends an operator hunting an alarm that cannot exist. Null means "no confirmed counterpart", never "not looked up yet". Where a profile has unmapped specs, the count is noted below.

Note The namespace column is what the metric stands in for, carried as an attribute. Proteus never publishes into any of these — a namespace beginning AWS/ is reserved and every request to it is rejected. See the reserved-prefix rule.

Runtimes and infra kinds#

Six runtimes: eks, ecs, ec2, lambda, managed, browser.

Eight infra kinds — the shared resources faults can contend over:

Fault kinds#

14, each with a severity in 0..1 and a time window. All compose through a single FaultEffect seam, so a fault does not need to know which archetype it lands on. Faults ramp rather than step, and reach other services by contention through shared infrastructure - not along depends_on. See the deep dive on faults.

Targets is the drop-target class the GUI palette enforces.

noisy-neighbor is the only infra-targeted kind. Aimed at a service it has no aggressor and is deliberately inert, so the palette will not offer it as a service drop target. Its two aggressor_* parameters are what make it asymmetric — the aggressor's CPU climbs while the victim's latency doubles — because a symmetric version is not findable, and finding it is the exercise.

Two pairs are deliberately hard to tell apart without reading more than one signal: slow-query is latency with flat CPU and flat errors, while thread-pool-rejection is errors with barely-moved latency. agent-quality-regression is the hardest of all, because every conventional signal stays healthy.

Guard policies#

Five. Set with --guard; the default is estimate-confirm.

--cap defaults to $50 and applies to budget-ceiling only. --dry-run on seed, live or firehose forces paranoid.

paranoid also disables the live pricing lookup and falls back to the built-in rate table. That is not an oversight: the projection runs before the guard can refuse anything, so a cold or stale pricing cache under paranoid would make an outbound AWS call before anything had a chance to stop it. A slightly staler cost figure buys a promise that actually holds.

Two policies print a banner, because both are surprising in opposite directions:

PARANOID GUARD: telemetry will be rendered and costed but NOTHING will be sent to AWS.

UNLIMITED GUARD: every projected record will be sent to AWS with no spend check and
no confirmation. You are responsible for the bill.

AWS ingestion limits#

Endpoints are HTTP only, no gRPC. OTLP 1.x, binary or JSON, gzip or none.

Per-request limits:

The 1,000-datapoint metrics cap is the tightest constraint in the system, and the +10-minute metrics future window is the tightest of the three. Proteus uses the tightest of each so one window is safe for every signal: −14 d to +10 min.

What Proteus actually batches at, deliberately under each ceiling:

Logs are capped at 1 MB in most regions and 20 MB in a handful — us-east-1, us-west-2, eu-west-1 "and others". Because the full list is not documented, the conservative 1 MB is used everywhere; the record cap binds first anyway.

Other limits that shaped the code:

• Metrics: 150 labels max per datapoint, 1,024 characters max per attribute value, 40 KB max metadata per series, 1M new series per 10-minute window.
• Traces: 200 KB max single span, 16 KB max per unique resource+scope.
• Logs: 1 MB max single event.
• CloudFormation: 51,200 bytes inline template, 1,000,000 bytes via S3.

The reserved AWS/ prefix#

You cannot publish to a namespace beginning AWS/. It is reserved and the request is rejected. ContainerInsights and ECS/ContainerInsights are reserved too.

So synthetic metrics go to the custom namespace proteus/{model-name} and carry their AWS counterpart in two attributes:

That lets the GUI say "this stands for pod_cpu_utilization_over_pod_limit in ContainerInsights" without ever writing into a reserved namespace. The rule is enforced in code — a profile spec whose name begins AWS/ raises at render — and asserted by the test suite against rendered records.

Environment variables#

Three are read by the tool. All are resolved at call time, never captured into a module-level constant, so a test or a side-by-side estate can isolate itself.

AWS_REGION is consulted as a fallback for PROTEUS_REGION. Standard AWS credential variables and AWS_PROFILE work as usual, since credentials are resolved by boto3 — --profile is the explicit override.

Note PROTEUS_VERSION is not an environment variable, despite appearing in the code. It is a constant resolved from installed package metadata, surfaced as the stack's ProteusVersion output and as a resource tag. Setting it in your shell does nothing.

proteus about prints the resolved state directory and region, which is the fastest way to find out that PROTEUS_HOME is set somewhere you forgot about.

State directory#

Contents of $PROTEUS_HOME (default ~/.proteus):

Warning Nothing in this directory belongs in git. It holds your sealed hunt answers, so committing it gives away every exercise. teardown does not touch it — delete it yourself for a genuinely clean machine.

CLI surface#

18 top-level commands. Every flag below was read from --help on this build.

docs and site build this documentation rather than any telemetry. They are listed because they appear in proteus --help, and a surface table that omits a command a reader can see is worse than no table.

Shared options#

--model <path> (world model path) appears on doctor, plan, import-cfn, import-live, bootstrap, teardown, seed, live, firehose, serve, show, chat and hunt start. It is absent from rename, which reads and writes the default model path only.

--profile <str> (AWS profile) appears on every command that needs credentials: doctor, bootstrap, teardown, seed, live, firehose, serve, chat, hunt start, hunt guess, import-live. It is absent from import-cfn, which is the flag-level consequence of that command making no AWS call at all.

--region <str> appears on the same set plus plan, import-cfn and import-live. Default is PROTEUS_REGION → AWS_REGION → us-west-2.

--stack <str> (stack name override) appears on doctor, bootstrap, teardown, seed, live and firehose. Without it, the name is proteus-{model-name}.

Per-command options#

proteus doctor

proteus plan

proteus rename {selector} {pattern}

Offline. Both arguments are required. Renames services by default, infra nodes with --infra, and rewrites every reference to the old name as it goes.

Name patterns#

The {pattern} argument. Two grammars, equivalent where they overlap — webserver00 is webserver{n:02}, and cache-## is cache-{rand:2}.

The counter rule, exactly: a maximal run of digits is a counter if and only if it consists entirely of zeros and is two or more characters long.

Read that as written rather than as a rule about what precedes the zeros, because the two readings differ in one case and agree everywhere a reader would think to check:

web-0010 is the only case that separates them: the rule looks at the whole run 0010, which is not entirely zeros, so nothing in it is a placeholder. A single 0 is likewise literal, so web0 and s3-bucket-0 keep their names. To put a counter after a digit, write it explicitly: svc-1{n:02} gives svc-101, svc-102, …

A pattern may hold one counter. web-00-shard-00 is refused, in either spelling, because two counters could reasonably move together, nest, or count independently. Ranges are exempt — they carry their own values, so web-{1..3}b{1..3} yields web-1b1, web-2b2, web-3b3.

Random placeholders seed from the model's own seed unless --seed overrides it, so a rename is reproducible from the world model alone.

Selectors#

The {selector} argument, matched against existing names.

Globs are full matches, so web* does not match myweb-tier — use *web*. Every other character is literal: web.server matches only web.server, and [abc] is three literal characters rather than a character class. Regexes are wrapped in slashes and matched with re.fullmatch, which makes ^ and $ redundant but harmless. ** is an alias for * and nothing more — service names are flat, with no separator to cross, so web**.server and web*.server select the same names. Zero matches is an empty result rather than an error.

proteus import-cfn <template>

Makes no AWS call. The template argument is required and is never modified.

proteus import-live

Reads a real account. Read-only — only Describe, List and Get, enforced by a client wrapper that raises before boto3 sees the call. GetMetricData is the only billed call. See the walkthrough for the limitation that is not visible in its output.

proteus bootstrap

proteus teardown

proteus seed

proteus live

proteus firehose — the same options as live with denser defaults: --minutes 10.0, --interval 10.0, --tick 10.0.

proteus serve

proteus chat takes an optional positional message. Omit it for a REPL; a blank line exits.

proteus hunt has four subcommands:

proteus show, proteus faults and proteus about take no options beyond --model on show.

Glossary#

Estate. The modeled distributed system as a whole: its services, their dependencies, the infrastructure they share, and the tenants that share it. What proteus show prints.

World model. The estate as data — a single JSON document at $PROTEUS_HOME/world.json, defined by proteus/model/schema.py. It is the only thing chat and hunt ever edit. Everything downstream is derived from it plus a seed, which is what makes runs reproducible. Carries a revision and a fingerprint, and the deployed stack records the fingerprint it was built from.

Archetype. One of the 12 hand-written workload types, with bespoke internal logic. A Kafka consumer's lag responds to its producer's rate because the archetype knows about both.

Profile. One of the 56 declarative workload types, each covering one AWS namespace. A profile declares its metrics rather than computing them, so adding an AWS service is a data edit. Reached through the custom archetype.

Tenant. A logical customer sharing infrastructure with other tenants. What makes noisy-neighbor possible: one tenant's aggression is another's unexplained latency. Rendered as node color on the GUI canvas.

Fault. An injected failure: one of the 14 kinds, aimed at a service or an infra node, with a severity in 0..1 and a start and end time. Ramps rather than steps. Reaches other services through shared infrastructure, not along depends_on.

Effect. The FaultEffect seam through which a fault reaches a workload. A fault composes effects — a latency multiplier, a CPU addend, an error-rate addend — so it does not need to know which archetype it lands on. Frozen contract; see Faults.

Tick. One instant of rendering for one service: a timestamp, an interval, the service, the model, the composed fault effect, and a seeded RNG. Generators receive ticks and yield records.

Window. A start, an end, and a sampling interval. Every render takes one. Clamped to the ingestible range, −14 d to +10 min.

Signal. One of the four telemetry types: metrics, logs, traces, rum. Each has its own endpoint, its own per-request caps, and its own emitter.

Record. A signal-neutral intermediate — MetricPoint, LogRecord, SpanRecord, RumEvent. The renderer produces records; emitters translate records into wire calls. This split is what makes faults testable without reading a console.

Seed. The RNG seed on the world model, default 1337. Same model plus same seed plus same window gives byte-identical telemetry.

seed (the command). Backfill: telemetry with backdated timestamps, up to 14 days, so the console is populated before you present. Not to be confused with the RNG seed above.

live. Stream telemetry with current timestamps, in cycles, while you narrate.

firehose. live with a much denser interval, to watch data arrive. Self-throttles below the account TPS ceilings so the run slows rather than collecting HTTP 429s.

Hunt. A fault-finding exercise. hunt start injects a hidden fault and seals the answer; you find it in CloudWatch Omni; hunt guess grades you on root cause, affected service and time window. The answer is withheld from show, from chat, from hunt list, and from the grader's own hint until you score 70 overall.

Guard. The cost policy that gates every injection. Five policies; all injecting commands go through one code path, so no mode can skip it.

Projection. The pre-flight estimate: record counts per signal, uncompressed wire bytes, request count, new metric series, and a dollar figure at list price. Deliberately pessimistic.