Skip to main content

​
What is TierZero.md?

TierZero.md is a special Markdown file that provides TierZero with organization-specific instructions that TierZero should always follow when processing requests.

​
Key Sections

A well-structured TierZero.md should include the following sections:

​
Company

High-level description of what your company does and the products you offer. This helps TierZero understand the business context of issues.

​
Customer Blast Radius

How to correlate logs, traces, metrics, and other observability data with:
  • The set of customers affected by an issue
  • The subset of environments affected (e.g., sharded infrastructure by region or other dimensions)

​
Environment

How to identify the production environment (Kubernetes cluster, region, database instance, etc.) in logs, tags, and traces. Include a brief description of the deployment setup.

​
Infrastructure as Code

Is infrastructure deployed as code? Where is it defined? Are there production resources not defined in code that are frequently used?

​
Code Release and Deployment

How services are released, how owned infrastructure is released, and whether there’s a system for non-deployment feature releases (e.g., feature flags).

​
Sample TierZero.md

### Company
Acme Corp is a SaaS platform that provides project management and collaboration tools for distributed teams. Our core products are:
- **Acme Projects**: Task and project management
- **Acme Docs**: Real-time collaborative documents
- **Acme Chat**: Team messaging and video calls

### Customer Blast Radius
Customers are identified by `org_id` in logs and traces. We use regional sharding:

| Tag/Attribute | Data Source | Description |
|---------------|-------------|-------------|
| `org_id` | Logs, Traces | Customer organization identifier |
| `region` | Logs, Metrics | Geographic region (us-east, eu-west, ap-south) |
| `cell_id` | Logs, Traces | Infrastructure cell within a region |
| `tier` | Logs | Customer tier (free, pro, enterprise) |

Enterprise customers (tier=enterprise) are on dedicated cells. Free/Pro customers share multi-tenant cells.

### Environment
Production runs on AWS EKS across three regions:
- `us-east-1` (primary)
- `eu-west-1` (EU customers)
- `ap-south-1` (APAC customers)

Identify production in observability data:
- Logs: `env:prod*` or `environment:production`
- Kubernetes namespace: `prod-*`
- Database instances: `prod-aurora-*`

### Infrastructure as Code
All infrastructure is defined in Terraform:
- Repository: `acme/infrastructure`
- Directory: `terraform/environments/prod/`

Exceptions not in IaC:
- DNS records managed in Cloudflare UI
- Some legacy Lambda functions in `acme/legacy-functions`

### Code Release and Deployment
- Services deploy via GitHub Actions → ArgoCD
- Deployments roll out via canary (10% → 50% → 100%)
- Feature flags managed in LaunchDarkly
  - Flag naming: `feature.<team>.<feature-name>`
  - Query flags: `source:launchdarkly @flag.key:*`

​
Per-Team Instructions

In addition to organization-level TierZero.md, you can configure team-specific instructions that apply only when working on that team’s alerts, digests, or questions. This allows different teams to have specialized context without cluttering the global instructions.

​
FAQ

​
What should I NOT include?

The following should be imported or configured separately:
  • A comprehensive list of all telemetry tags (include only the most critical ones)
  • Detailed dashboards and notebooks
  • Full runbook documentation (reference the location instead)

​
How detailed should it be?

Use specific names, identifiers, and examples. Tables are preferred for tag/attribute references. Keep each section concise (a few paragraphs max) — TierZero can always dig deeper into your integrations for more detail.