Quick Start

Install Proteus and get synthetic telemetry into CloudWatch with four commands.

Four commands take you from nothing to a populated CloudWatch console. Read the cost callout before the fourth one.

Install#

Python 3.12 or newer.

git clone <your-fork> proteus && cd proteus
python3.12 -m venv .venv && .venv/bin/pip install -e .

That puts a proteus command in .venv/bin. An alias saves typing:

echo "alias proteus='$PWD/.venv/bin/proteus'" >> ~/.zshrc

Then set up AWS credentials for a region where Omni is available — us-east-1, us-west-2 or eu-west-1. Every command defaults to us-west-2; pass --region to change it.

1. Plan the estate#

proteus plan

wrote northwind-rx to ~/.proteus/world.json: 18 services, 8 infra nodes, 3 tenants
next: proteus bootstrap then proteus seed

This writes a world model — a JSON document describing the fictional estate. No AWS call, no cost. proteus show prints what you got.

northwind-rx is the default because it is the one big enough to hide an incident in. Six smaller presets ship with it, and the smaller the estate the cheaper every command after this one:

proteus plan --preset web-server    # 1 service
proteus plan --preset alb-fleet     # 3 services: an ALB, a ten-instance fleet, a database
proteus plan --preset three-tier    # 5 services: an ALB, web and app tiers, a cache and a database
proteus plan --preset ai-chatbot    # 6 services: browser, API, Bedrock agent, vector store
proteus plan --preset ml-pipeline   # 8 services: Kinesis to S3 to EMR to SageMaker, via MWAA

Pick by the shape you want to point at in the console. The seven presets gives the full table, including why ml-pipeline wants --interval 300 and the other six do not.

2. Deploy the scaffolding#

proteus bootstrap

This deploys a CloudFormation stack of 47 resources for the default estate: 18 log groups, 27 alarms, an SNS topic and a RUM app monitor. Log groups have to exist before you backfill, because the logs endpoint rejects a batch for a group that does not exist.

bootstrap also refuses a log retention shorter than the backfill horizon you intend to seed. CloudWatch Logs accepts a backdated event with HTTP 200 and then silently drops it if it predates retention, so that guard is the difference between a populated console and an empty one.

3. Check it before you spend anything#

proteus doctor

doctor is read-only and it is not decoration. It catches the failures that otherwise surface five minutes before a demo. Here is a real run on a machine whose SSO session had expired — the most common first-run failure:

 check         ┃      ┃ detail
━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 region        │ OK   │ us-west-2 supports CloudWatch Omni
 credentials   │ FAIL │ could not resolve credentials: TokenRetrievalError:
               │      │ Error when retrieving token from sso: Token has expired
               │      │ and refresh failed
 world model   │ OK   │ northwind-rx rev 1: 18 services, 8 infra, 3 tenants, 0
               │      │ fault(s), fingerprint d7caf912a5a9862f
 template size │ WARN │ template 37,797 bytes across 47 resources, sent inline
               │      │ (74% of the 51,200-byte limit)

suggested fixes
  credentials: aws sso login   (or refresh whatever provides this profile)
  template size: no action needed: bootstrap stages large templates to S3
automatically

Every FAIL and WARN names the command that fixes it. With working credentials, doctor additionally checks Transaction Search, log group retention, the deployed stack against your current model, and Bedrock access for chat and hunt.

Fix every FAIL before going on. A WARN is safe to proceed past.

4. Backfill history#

Cost seed makes real API calls and CloudWatch bills you for it. A 14-day backfill of the 18-service default estate, at a 60-second interval, projects about 8.0M spans, 9.4M metric points, 1.9M log events and 484k RUM events — 4.8 GiB on the wire, estimated at about $153, list price in us-west-2. Add services and the figure goes up. It is list price only: it cannot see your discounts or credits, and it deliberately charges a full metric-month for every new metric series rather than prorating, so a short run looks dearer than it bills.

proteus seed

Before it sends anything, seed prints the projection for your region and estate and waits for a yes. This one is the 18-service default estate over 14 days in us-west-2:

Projected volume
  spans                7,983,360
  metric points        9,354,240
  log events           1,874,880
  RUM events             483,840
  new metric series          469

Projected wire traffic (uncompressed)
  traces                 3.1 GiB
  metrics                1.0 GiB
  logs                 679.4 MiB
  total                  4.8 GiB
  requests                12,762

Estimated cost  ~ $152.53 USD  (approximate, not a quote)

Below that it prints its own caveats — which rates came from the live AWS Pricing API, and why the figure is an over-estimate — then asks Send this telemetry?, defaulting to no. Nothing leaves the machine until you answer yes.

Three ways to spend less:

proteus seed --dry-run          # render and size everything, send nothing
proteus seed --days 1           # one day instead of fourteen
proteus plan --preset web-server --force && proteus bootstrap   # 1 service, not 18

The preset is the biggest lever of the three, because volume tracks the number of services: web-server is one service against the default's eighteen. Changing the preset changes the estate, so bootstrap again before you seed — the new model needs its own log groups, and doctor will tell you if you forget.

Confirm it worked#

Open CloudWatch in the region you injected into and check three things.

The Omni service map shows the estate. api-gateway should fan out to checkout, search, account, rx-advisor and rx-refills — the same edges proteus show prints under depends on.
Log groups named /proteus/northwind-rx/<service> hold events.
Transaction Search returns spans across the window you backfilled.

Data takes a few minutes to appear. If the service map is still empty after that, go to Troubleshooting. An empty map after a seed that reported success usually means Transaction Search has destination XRay rather than CloudWatchLogs, in which case every span was rejected with HTTP 400 — proteus doctor reports that as a FAIL.

Next#

proteus serve

That opens the web GUI on 127.0.0.1:8787, where you compose the estate on a canvas, drag faults onto services, and watch the cost projection move before you inject. Worked examples for both the GUI and the CLI are in Operations.

To understand what you just ran, read Overview. To take the estate down again, proteus teardown shows exactly what it will delete first.