Skip to main content

Scenario 06: Investigate a performance problem

Investigate code paths behind a measured performance problem and verify a change with the same workload and correctness checks.

User Guides

Use this scenario when you have a measured latency, throughput, CPU, memory, I/O, or contention problem and need to narrow the responsible code. CodeGraph ranks structural candidates and shows their callers. Static analysis forms a hypothesis; measurements with the selected workload show its performance impact.

The scenario first tries handlers for common query types. For other queries, it combines pattern-based detection of potential bottlenecks, call graph analysis, and resource analysis. The graph helps identify related functions, cycles, and call paths. The scenario uses these findings to prepare recommendations and prioritize the investigation.

Use the result alongside a profile of your workload. For example, when response time increases with concurrency, start with the functions in the slow trace. Match them to CodeGraph’s candidates, inspect their dependencies, and select one area for an experiment. Measure the change with the same workload to connect the structural finding to the observed result.

Define the measurement first

Record the workload, input data, warm-up, concurrency, sample count, percentile or throughput metric, hardware, runtime and configuration. Keep the same conditions before and after the change.

{
  "measurement_environment": "<hardware, runtime, config, dataset>",
  "baseline_measurement": "<metric, value, sample count>",
  "candidate_measurement": "<same metric after the change>"
}

Save a stable baseline measurement. After changing code complexity or the call chain, repeat the measurement and compare the results.

Typed investigation request

Prepare the environment using the CLI guide, and configure the project, graph, and LLM provider using the programmatic guide. Run Python from the CodeGraph repository root. This template requires an existing accepted task: replace project_key, namespace, <task-id>, measurement references, and the source path with its exact values. References must lead to accessible profiling and measurement results; placeholders do not create those results.

Before investigating, prepare the registered project and CPG for the revision used by the profile or trace. Use the role-bound developer scenario with an accepted task:

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Rank code paths that could explain the measured request-latency regression.",
    employee_id="codegraph_developer",
    scenario_id="scenario_06",
    event_type="implementation_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<profile-or-trace-ref>", "<benchmark-ref>"],
        "file_paths": ["<bounded-source-path>"],
    },
)

result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
print(result["scenario_id"])
print(result.get("answer") or "")

Missing project_key, namespace, or task_id fails closed with role_bound_scenario_contract_missing. The scenario is conditional for codegraph_developer; the request should name a real performance symptom.

Expect scenario_06 and an answer connecting candidate paths to the supplied symptom. Check metadata.role_bound_scenario_invocation, the current revision, and code references. An error, empty answer, or stale graph does not establish success. For a negative check, pass context={}: the call must raise RuntimeError containing role_bound_scenario_contract_missing before investigation. Restore the exact scope before retrying.

Inspect the blast radius

In PowerShell, replace <symbol> with an existing method name and <cpg-path> with the selected project database. The command requires a reachable GoCPG gRPC service:

python -m src.cli impact "<symbol>" --db "<cpg-path>" --format json

Use callers, affected methods, depth and impact score to select the area to verify. If the relationship list is empty, check the symbol name and CPG freshness, then compare the relationships with the source. Confirm the change with tests and performance measurements at the selected revision.

Tests-first optimization loop

  1. Reproduce the problem with the recorded workload and save baseline_measurement.
  2. Use profiles, traces or counters to connect the symptom to one bounded code path.
  3. Use CodeGraph to inspect callers, dependencies and risk around that path.
  4. Add a correctness regression test and, when stable enough, a performance threshold or comparison test.
  5. Make one small change without mixing unrelated cleanup.
  6. Run correctness tests, the same benchmark and the same profiler configuration.
  7. Save candidate_measurement, variance and any regressions; keep the change only when the improvement is repeatable.

Compare distributions or several runs. State uncertainty when the difference is within normal noise.

Stop conditions

Proceed after reproducing the measurement in the same environment and data, keeping the candidate within the approved API, authorization, and persistence boundaries and preserving correctness and security. Return the hypothesis and missing evidence until the required checks pass.

Use Feature Development to prepare implementation changes and Code Review for revision-bound review evidence.

Report a documentation issue