Runtime Analysis
Analyze runtime observability data — distributed traces, structured logs, and APM metrics — to produce runtime behavior documentation for individual services (P1-13) and system-wide profiles (P2-13).
When to Use
- Generating P1-13 Runtime Behavior Profile for a service
- Generating P2-13 System Runtime Profile across all services
- Validating P1-4 dependency declarations against observed runtime behavior
- Identifying undocumented dependencies, dead code paths, or real bottlenecks
Data Source Requirements
| Data Type |
Purpose |
Common Tools |
| Distributed traces |
Service call graphs, latency, hot paths |
OpenTelemetry, Jaeger, Zipkin, Application Insights, Datadog APM, New Relic |
| Structured logs |
Error patterns, anomalies, undocumented behaviors |
ELK Stack, Splunk, Azure Monitor Logs, CloudWatch Logs |
| APM metrics |
Resource utilization, SLI baselines, throughput |
Application Insights, Datadog, New Relic, Prometheus + Grafana |
Procedure
For P1-13 (Single Service)
- Identify data sources — Determine which observability tools are available for this service
- Extract trace data — Follow trace analysis procedures:
- Service call patterns (who calls this service, who does it call)
- Latency percentiles (p50, p95, p99)
- Hot paths (highest-volume endpoints)
- Extract log data — Follow log analysis procedures:
- Error rates and top error categories
- Anomaly patterns
- Undocumented dependency signals
- Extract metrics — Follow metrics interpretation procedures:
- CPU and memory utilization patterns
- Request throughput
- Message processing rates
- Validate dependencies — Compare observed trace dependencies against P1-4 declared dependencies
- Write outputs — Populate
runtime-behavior.yaml and runtime-behavior.md
For P2-13 (System-Wide)
- Aggregate all P1-13 outputs across repos
- Build system-wide latency heatmap — Service × Service matrix
- Build traffic flow diagram — Mermaid with edge weights proportional to volume
- Identify system bottlenecks — Highest p99, highest error rate, highest resource utilization
- Trace critical business paths — End-to-end for key transactions
- Write output — Populate
system-runtime-profile.md
Data Format Notes
If trace/log/metric data is provided as:
- JSON exports: Parse directly, extract relevant fields
- CSV exports: Parse as tabular data, map columns to schema
- Screenshots/dashboard images: Describe visually, note this is approximate data
- API access: Query the observability tool's API (provide query templates)
- Manual input: Accept user-provided values and note the source
When exact data is unavailable, document what is known and mark gaps with data-source: "estimated" or data-source: "unavailable".
1---2name: runtime-analysis3description: Analyze runtime observability data (distributed traces, structured logs, APM metrics) to generate runtime behavior documentation. Use when producing P1-13 runtime-behavior artifacts or P2-13 system runtime profiles. Covers OpenTelemetry, Jaeger, Zipkin, Application Insights, Datadog, New Relic trace analysis, structured log extraction, and APM metrics interpretation.4---56# Runtime Analysis78Analyze runtime observability data — distributed traces, structured logs, and APM metrics — to produce runtime behavior documentation for individual services (P1-13) and system-wide profiles (P2-13).910## When to Use1112- Generating P1-13 Runtime Behavior Profile for a service13- Generating P2-13 System Runtime Profile across all services14- Validating P1-4 dependency declarations against observed runtime behavior15- Identifying undocumented dependencies, dead code paths, or real bottlenecks1617## Data Source Requirements1819| Data Type | Purpose | Common Tools |20|---|---|---|21| Distributed traces | Service call graphs, latency, hot paths | OpenTelemetry, Jaeger, Zipkin, Application Insights, Datadog APM, New Relic |22| Structured logs | Error patterns, anomalies, undocumented behaviors | ELK Stack, Splunk, Azure Monitor Logs, CloudWatch Logs |23| APM metrics | Resource utilization, SLI baselines, throughput | Application Insights, Datadog, New Relic, Prometheus + Grafana |2425## Procedure2627### For P1-13 (Single Service)28291. **Identify data sources** — Determine which observability tools are available for this service302. **Extract trace data** — Follow [trace analysis procedures](./references/trace-analysis.md):31 - Service call patterns (who calls this service, who does it call)32 - Latency percentiles (p50, p95, p99)33 - Hot paths (highest-volume endpoints)343. **Extract log data** — Follow [log analysis procedures](./references/log-analysis.md):35 - Error rates and top error categories36 - Anomaly patterns37 - Undocumented dependency signals384. **Extract metrics** — Follow [metrics interpretation procedures](./references/metrics-interpretation.md):39 - CPU and memory utilization patterns40 - Request throughput41 - Message processing rates425. **Validate dependencies** — Compare observed trace dependencies against P1-4 declared dependencies436. **Write outputs** — Populate `runtime-behavior.yaml` and `runtime-behavior.md`4445### For P2-13 (System-Wide)46471. **Aggregate all P1-13 outputs** across repos482. **Build system-wide latency heatmap** — Service × Service matrix493. **Build traffic flow diagram** — Mermaid with edge weights proportional to volume504. **Identify system bottlenecks** — Highest p99, highest error rate, highest resource utilization515. **Trace critical business paths** — End-to-end for key transactions526. **Write output** — Populate `system-runtime-profile.md`5354## Data Format Notes5556If trace/log/metric data is provided as:57- **JSON exports**: Parse directly, extract relevant fields58- **CSV exports**: Parse as tabular data, map columns to schema59- **Screenshots/dashboard images**: Describe visually, note this is approximate data60- **API access**: Query the observability tool's API (provide query templates)61- **Manual input**: Accept user-provided values and note the source6263When exact data is unavailable, document what is known and mark gaps with `data-source: "estimated"` or `data-source: "unavailable"`.
ricardocovo