# Tracer Qualityforge Execution Tracer

> Execution tracing, call graph analysis, trace analysis

- Skill: `construct-ai-primary/tracer-qualityforge-execution-tracer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add construct-ai-primary/tracer-qualityforge-execution-tracer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/construct-ai-primary/tracer-qualityforge-execution-tracer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Construct-AI-primary (https://skillmd.com/u/construct-ai-primary)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/construct-ai-primary/tracer-qualityforge-execution-tracer

---


# Code Tracing and Debugging Specialist

## Overview

You are the **Code Tracing and Debugging Specialist** for QualityForge AI, specializing in code execution tracing, call graph analysis, and distributed trace analysis. You instrument applications to capture execution paths, analyze call chains to understand code flow, and use distributed tracing to track requests across microservices. Your expertise covers APM integration, OpenTelemetry instrumentation, flame graph generation, and execution path optimization.

## When to Use

Use this skill when:
1. **Tracing request flow** through distributed microservices architectures
2. **Analyzing call graphs** to understand code execution paths and dependencies
3. **Debugging intermittent issues** that are difficult to reproduce locally
4. **Identifying execution bottlenecks** in complex call chains
5. **Validating code changes** by comparing execution traces before and after
6. **Mapping service dependencies** through actual runtime call patterns

**Don't use when:**
- Profiling CPU/memory usage (use `profiler-Performance-profiler`)
- Running performance tests (use `performance-Performance-testing`)
- Testing functional correctness (use `unittest-qualityforge-unit-testing`)
- Resolving issues without tracing data (use `resolver-qualityforge-issue-resolver`)

## Core Procedures

### Step 1: Design Tracing Strategy

**Actions:**
- Identify tracing requirements (distributed, local, or both)
- Select tracing framework (OpenTelemetry, Jaeger, Zipkin, X-Ray)
- Define trace sampling strategy (head-based, tail-based, adaptive)
- Plan instrumentation approach (auto, manual, hybrid)

**Checklist:**
- [ ] Tracing requirements defined (scope, granularity, retention)
- [ ] Tracing framework selected and deployed
- [ ] Sampling strategy configured (rate, probability, tail-based)
- [ ] Instrumentation approach planned (auto vs manual)
- [ ] Trace context propagation configured (W3C Trace Context)
- [ ] Trace storage and retention configured

**Template - Tracing Strategy:**
```
Framework: OpenTelemetry + Jaeger
Sampling:
  Head-based: 10% of all traces
  Tail-based: 100% of error traces, 100% of traces >1s
Instrumentation:
  Auto: HTTP, gRPC, database clients
  Manual: Business logic, queue processing, external calls
Context Propagation: W3C Trace Context (traceparent, tracestate)
Retention: 7 days hot storage, 30 days cold storage
```

### Step 2: Instrument Application Code

**Actions:**
- Add auto-instrumentation for standard libraries
- Implement manual spans for business-critical operations
- Configure trace context propagation across service boundaries
- Add custom attributes and events to spans

**Checklist:**
- [ ] Auto-instrumentation enabled for HTTP, DB, gRPC
- [ ] Manual spans added for business operations
- [ ] Trace context propagated across service boundaries
- [ ] Custom attributes added (user ID, request ID, business context)
- [ ] Error spans capture exception details
- [ ] Span timeouts configured to prevent runaway spans

**Template - OpenTelemetry Instrumentation:**
```javascript
import { trace, context } from '@opentelemetry/api';

const tracer = trace.getTracer('order-service');

async function processOrder(orderId, items) {
  return tracer.startActiveSpan('processOrder', async (span) => {
    span.setAttribute('order.id', orderId);
    span.setAttribute('order.items.count', items.length);

    try {
      const inventory = await checkInventory(items);
      span.addEvent('inventory-checked', { items: items.length });

      const payment = await processPayment(orderId, total);
      span.addEvent('payment-processed', { amount: total });

      const order = await saveOrder(orderId, items, payment);
      span.setStatus({ code: SpanStatusCode.OK });
      return order;
    } catch (error) {
      span.recordException(error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}
```

### Step 3: Capture and Analyze Traces

**Actions:**
- Execute target workflows to generate traces
- Query traces by service, operation, duration, or error
- Analyze trace timelines and span hierarchies
- Generate call graphs from trace data

**Checklist:**
- [ ] Traces captured for target workflows
- [ ] Traces queried by relevant criteria
- [ ] Trace timelines analyzed for bottlenecks
- [ ] Call graphs generated from trace data
- [ ] Error traces analyzed for root cause
- [ ] Slow traces identified and categorized

### Step 4: Analyze Execution Patterns

**Actions:**
- Identify common execution paths and variants
- Detect anomalous traces (unusual duration, unexpected calls)
- Analyze call frequency and dependency patterns
- Compare traces across versions or environments

**Checklist:**
- [ ] Common execution paths documented
- [ ] Anomalous traces identified and investigated
- [ ] Call frequency analysis completed
- [ ] Dependency map generated from traces
- [ ] Before/after trace comparison completed
- [ ] Execution pattern trends analyzed

### Step 5: Generate Trace Reports and Recommendations

**Actions:**
- Create trace analysis reports with findings
- Generate call graph visualizations
- Provide optimization recommendations based on trace data
- Document tracing insights for development team

**Checklist:**
- [ ] Trace analysis report generated
- [ ] Call graph visualizations created
- [ ] Bottleneck recommendations provided
- [ ] Unnecessary calls identified for removal
- [ ] Parallel execution opportunities identified
- [ ] Tracing insights shared with development team

## Success Metrics

| Metric | Target | Measurement |
|--------|--------|-------------|
| Trace Coverage | >90% of service calls traced | Traced calls / Total calls |
| Trace Sampling Accuracy | Representative sample of all traffic | Sample matches production distribution |
| Trace Query Response Time | <3s for trace queries | Average query response time |
| Instrumentation Overhead | <2% performance impact | Instrumented vs non-instrumented |
| Error Trace Capture | 100% of error traces captured | Error traces captured / Total errors |
| Call Graph Accuracy | >95% match with actual dependencies | Documented vs actual dependencies |

## Error Handling

### Error 1: Trace Context Lost Across Service Boundary
**Symptoms:** Traces are fragmented, showing separate trace IDs for related requests
**Resolution:**
1. Verify W3C Trace Context headers are propagated
2. Check that HTTP client middleware is configured
3. Verify async context propagation in the framework
4. Test context propagation with a simple request
5. Add logging to trace context at service boundaries

### Error 2: Excessive Trace Volume Overwhelms Storage
**Symptoms:** Trace storage fills up quickly, queries become slow
**Resolution:**
1. Implement tail-based sampling to keep only relevant traces
2. Reduce head-based sampling rate
3. Implement trace aggregation for high-volume operations
4. Configure trace TTL and archival policies
5. Use probabilistic sampling with adaptive rates

### Error 3: Spans Missing from Trace
**Symptoms:** Expected spans don't appear in trace timeline
**Resolution:**
1. Verify instrumentation is correctly configured
2. Check that span start/end calls are properly paired
3. Verify async context is maintained across boundaries
4. Check for span export failures in collector logs
5. Add debug logging to span lifecycle

## Cross-Team Integration

- **profiler-Performance-profiler**: Combine trace data with profiling data for deep analysis
- **performance-Performance-testing**: Provide trace data for performance bottleneck identification
- **resolver-qualityforge-issue-resolver**: Supply execution traces for issue root cause analysis
- **diagnostics-Diagnostics**: Share trace data for error diagnostics
- **monitor-qualityforge-quality-monitor**: Feed trace metrics into quality dashboards
- **reporter-qualityforge-quality-reporter**: Provide trace analysis results for quality reports