Skip to main content

View Markdown · Documentation index (llms.txt)

State 007 Learning Guide

Explain behavior with telemetry​

When a trade seems to disappear, a healthy service status gives little help. This chapter is for developers diagnosing a distributed workflow: use complementary telemetry signals to narrow a question, and learn why missing telemetry cannot settle it.

How to learn with TraderX states · Structured lesson JSON

Maturity: implemented. Run the exercises in a disposable local environment; use the quickstart for setup and cleanup.

Starting point​

NATS and PostgreSQL carry the workflow, but scattered logs make diagnosis difficult.

Entry route: combined. Bring the knowledge from every declared predecessor.

From 006-messaging-nats-replacement​

Predecessor guide

  • Carry forward: Replace internal messaging with NATS while preserving the trade-to-position workflow.
  • Why move: NATS and PostgreSQL carry the workflow, but scattered logs make diagnosis difficult.
  • Add or revise: Add LGTM telemetry to connect a user action with logs, metrics and traces.
  • Evidence to collect: The signals provide complementary evidence. Record which services are represented and which gaps remain instead of treating an empty panel as a successful run. Missing telemetry can reflect selection, sampling or collection problems. It is not evidence that no trade exists.
  • Objectives: trace-increment, interpret-evidence
BeforeAfter
NATS and PostgreSQL carry the workflow, but scattered logs make diagnosis difficult.Add LGTM telemetry to connect a user action with logs, metrics and traces.

Concepts before tools​

  • A metric summarizes measurements; a log records an event; a trace relates timed operations. Correlation is evidence of a path, not proof that every business effect committed.

Runtime prerequisites: Use the state quickstart for tool versions, generation, start and stop commands. Run one local state at a time because ports and generated output directories are shared.

Learning objectives​

  • trace-increment: Correlate one trade with available logs, metrics and traces, and identify gaps in the observed request path.
  • interpret-evidence: Explain the evidence boundary: Missing telemetry can reflect selection, sampling or collection problems. It is not evidence that no trade exists.

Guided walkthrough​

1. observe (available)​

Objectives: trace-increment.

Start this state and open Grafana through /grafana/ as described in the quickstart. Submit one small trade and note its time and identifier. Find the relevant service logs and metrics, and inspect any available trace for that request.

Expected observation and meaning: The signals provide complementary evidence. Record which services are represented and which gaps remain instead of treating an empty panel as a successful run.

Supporting material: quickstart · architecture · runtime-topology.

2. challenge (available)​

Objectives: interpret-evidence.

Change the dashboard time range to exclude the request and compare it with a range that includes it. If a trace is absent, inspect instrumentation and collection health before concluding the request did not run.

Expected observation and meaning: Missing telemetry can reflect selection, sampling or collection problems. It is not evidence that no trade exists.

Supporting material: spec · contract-delta.

Demonstrate your understanding​

Question (trace-increment, interpret-evidence): Can you diagnose a missing trade from an empty dashboard alone?

Assessment guidance: No. Check time range and collection, then reconcile the persisted trade and processing evidence. Name the limits of the available signals.

Work with a learning partner​

Use the learning-partner protocol with a human or an agent. Ask for a prediction before running the exercise, offer one hint at a time, and discuss the assessment guidance after the learner has attempted an explanation.

Objectives: trace-increment, interpret-evidence.

Check the starting point: What question can a log answer that a service-health indicator cannot?

Ask before the experiment: Predict what an empty dashboard means when the time range excludes your request.

Hints, in order:

  1. Check the selected time window and whether the collector received any signals.
  2. Compare the available logs, metrics and trace with the separately recorded trade identifier.

Misconception to probe (not a fact): Missing telemetry proves that the business action never occurred.

Evidence to ask the learner for: Ask for the request time, selected range, available correlated signals and missing spans; distinguish telemetry gaps from absent business records.

Scope and limitations​

  • Missing telemetry can reflect selection, sampling or collection problems. It is not evidence that no trade exists.
  • This is an educational local demonstration. Passing its checks does not establish production readiness, financial settlement, or correctness under every failure mode.

Position In Learning Graph​

Convergence Metadata​

Rendered Code​

Code Comparison With Previous State​

Plain-English Code Delta​

  • Flow Impact: No functional flow changes from state 006.
  • Flow Impact: Existing flow IDs remain valid; this state only adds runtime observability capabilities.

Run This State​

./scripts/start-state-007-observability-lgtm-compose-generated.sh