# maxymfarenyk/tracing-tax architecture

> Architecture diagram of the GitHub repository maxymfarenyk/tracing-tax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxymfarenyk/tracing-tax
- Repository: https://github.com/maxymfarenyk/tracing-tax

## Overview

tracing-tax is a research stand for measuring how trace-sampling strategies affect a checkout microservice system. Locust drives requests through the gateway; orders coordinates inventory reservations and simulated payments, while services export traces through the collector to Jaeger. Scenario configuration selects head, tail, or adaptive sampling. Prometheus and Grafana expose resource and collector metrics. The experiment runner gathers load, metrics, and retained traces into CSV; analysis turns runs into summaries and charts. Documented topology and capabilities are shown alongside source-visible service calls; infrastructure wiring is primarily documented in the README.

Main entry points: [`services/gateway/app.py`](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/gateway/app.py) (Gateway), [`collector/configs`](https://github.com/maxymfarenyk/tracing-tax/tree/main/collector/configs) (OTel Collector), [`services/common/downstream.py`](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/common/downstream.py) (HTTP client helper), [`monitoring/prometheus.yml`](https://github.com/maxymfarenyk/tracing-tax/blob/main/monitoring/prometheus.yml) (Prometheus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_checkout["Checkout services"]
  node_gateway["Gateway<br/>[app.py]"]
  node_orders["Orders<br/>[app.py]"]
  node_inventory["Inventory<br/>[app.py]"]
  node_payments["Payments<br/>[app.py]"]
  node_downstream["HTTP client helper<br/>[downstream.py]"]
  node_faults["Fault injection<br/>[faults.py]"]
end

subgraph group_tracing["Tracing pipeline"]
  node_scenario["Sampling scenarios"]
  node_adaptive["Adaptive sampler<br/>[__init__.py]"]
  node_collector["OTel Collector"]
  node_jaeger["Jaeger<br/>[config.yaml]"]
end

subgraph group_monitoring["Monitoring"]
  node_cadvisor["cAdvisor<br/>[docker-compose.yml]"]
  node_prometheus["Prometheus<br/>[prometheus.yml]"]
  node_grafana["Grafana"]
end

subgraph group_experiment["Experiment workflow"]
  node_experiment_runner["Experiment runner<br/>[run_experiment.py]"]
  node_load_profile["Load profile<br/>[locustfile.py]"]
  node_trace_check["Trace verification<br/>[verify_trace.py]"]
  node_monitor_check["Monitoring verification"]
  node_sampling_check["Sampling verification<br/>[verify_sampling.py]"]
  node_runs["Run dataset<br/>[runs.csv]"]
end

subgraph group_analysis["Results analysis"]
  node_analyzer["Results analyzer<br/>[analyze.py]"]
  node_summaries["Summaries and charts"]
end

node_locust(("Locust load"))
node_redis[("Redis")]

node_locust -->|"sends requests"| node_gateway
node_load_profile -->|"targets"| node_gateway
node_gateway -->|"calls"| node_downstream
node_downstream -->|"HTTP request"| node_orders
node_orders -->|"calls"| node_downstream
node_downstream -->|"HTTP request"| node_inventory
node_downstream -->|"HTTP request"| node_payments
node_inventory -->|"increments stock"| node_redis
node_gateway -->|"injects faults"| node_faults
node_orders -->|"injects faults"| node_faults
node_inventory -->|"injects faults"| node_faults
node_payments -->|"injects faults"| node_faults
node_scenario -->|"selects configuration"| node_collector
node_scenario -->|"enables strategy"| node_adaptive
node_gateway -->|"exports traces"| node_collector
node_orders -->|"exports traces"| node_collector
node_inventory -->|"exports traces"| node_collector
node_payments -->|"exports traces"| node_collector
node_collector -->|"exports traces"| node_jaeger
node_cadvisor -->|"provides metrics"| node_prometheus
node_collector -->|"exposes metrics"| node_prometheus
node_prometheus -->|"supplies dashboards"| node_grafana
node_experiment_runner -->|"runs load"| node_load_profile
node_experiment_runner -->|"queries metrics"| node_prometheus
node_experiment_runner -->|"queries traces"| node_jaeger
node_experiment_runner -->|"writes rows"| node_runs
node_analyzer -->|"reads runs"| node_runs
node_analyzer -->|"writes reports"| node_summaries
node_trace_check -->|"sends request"| node_gateway
node_trace_check -->|"queries trace"| node_jaeger
node_monitor_check -->|"sends requests"| node_gateway
node_monitor_check -->|"checks metrics"| node_prometheus
node_sampling_check -->|"sends requests"| node_gateway
node_sampling_check -->|"uses query helpers"| node_monitor_check
node_sampling_check -->|"reads settings"| node_scenario

click node_gateway "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/gateway/app.py"
click node_orders "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/orders/app.py"
click node_inventory "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/inventory/app.py"
click node_payments "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/payments/app.py"
click node_downstream "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/common/downstream.py"
click node_faults "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/common/faults.py"
click node_scenario "https://github.com/maxymfarenyk/tracing-tax/tree/main/scenarios"
click node_adaptive "https://github.com/maxymfarenyk/tracing-tax/blob/main/services/adaptive_sampler/src/adaptive_sampler/__init__.py"
click node_collector "https://github.com/maxymfarenyk/tracing-tax/tree/main/collector/configs"
click node_jaeger "https://github.com/maxymfarenyk/tracing-tax/blob/main/jaeger/config.yaml"
click node_cadvisor "https://github.com/maxymfarenyk/tracing-tax/blob/main/docker-compose.yml"
click node_prometheus "https://github.com/maxymfarenyk/tracing-tax/blob/main/monitoring/prometheus.yml"
click node_grafana "https://github.com/maxymfarenyk/tracing-tax/tree/main/monitoring/grafana"
click node_experiment_runner "https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/run_experiment.py"
click node_load_profile "https://github.com/maxymfarenyk/tracing-tax/blob/main/load/locustfile.py"
click node_trace_check "https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/verify_trace.py"
click node_monitor_check "https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/verify_monitoring.py"
click node_sampling_check "https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/verify_sampling.py"
click node_runs "https://github.com/maxymfarenyk/tracing-tax/blob/main/results/raw/runs.csv"
click node_analyzer "https://github.com/maxymfarenyk/tracing-tax/blob/main/analysis/analyze.py"
click node_summaries "https://github.com/maxymfarenyk/tracing-tax/tree/main/results/analysis"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_orders,node_inventory,node_payments,node_downstream,node_faults toneBlue
class node_scenario,node_adaptive,node_collector,node_jaeger,node_redis toneAmber
class node_cadvisor,node_prometheus,node_grafana toneMint
class node_experiment_runner,node_load_profile,node_trace_check,node_monitor_check,node_sampling_check,node_runs toneRose
class node_analyzer,node_summaries,node_locust toneIndigo
```

## Components

### Checkout services

- [Gateway](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/gateway/app.py): `services/gateway/app.py`
- [Orders](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/orders/app.py): `services/orders/app.py`
- [Inventory](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/inventory/app.py): `services/inventory/app.py`
- [Payments](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/payments/app.py): `services/payments/app.py`
- [HTTP client helper](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/common/downstream.py): `services/common/downstream.py`
- [Fault injection](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/common/faults.py): `services/common/faults.py`

### Tracing pipeline

- [Sampling scenarios](https://github.com/maxymfarenyk/tracing-tax/tree/main/scenarios): `scenarios`
- [Adaptive sampler](https://github.com/maxymfarenyk/tracing-tax/blob/main/services/adaptive_sampler/src/adaptive_sampler/__init__.py): `services/adaptive_sampler/src/adaptive_sampler/__init__.py`
- [OTel Collector](https://github.com/maxymfarenyk/tracing-tax/tree/main/collector/configs): `collector/configs`
- [Jaeger](https://github.com/maxymfarenyk/tracing-tax/blob/main/jaeger/config.yaml): `jaeger/config.yaml`

### Monitoring

- [cAdvisor](https://github.com/maxymfarenyk/tracing-tax/blob/main/docker-compose.yml): `docker-compose.yml`
- [Prometheus](https://github.com/maxymfarenyk/tracing-tax/blob/main/monitoring/prometheus.yml): `monitoring/prometheus.yml`
- [Grafana](https://github.com/maxymfarenyk/tracing-tax/tree/main/monitoring/grafana): `monitoring/grafana`

### Experiment workflow

- [Experiment runner](https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/run_experiment.py): `scripts/run_experiment.py`
- [Load profile](https://github.com/maxymfarenyk/tracing-tax/blob/main/load/locustfile.py): `load/locustfile.py`
- [Trace verification](https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/verify_trace.py): `scripts/verify_trace.py`
- [Monitoring verification](https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/verify_monitoring.py): `scripts/verify_monitoring.py`
- [Sampling verification](https://github.com/maxymfarenyk/tracing-tax/blob/main/scripts/verify_sampling.py): `scripts/verify_sampling.py`
- [Run dataset](https://github.com/maxymfarenyk/tracing-tax/blob/main/results/raw/runs.csv): `results/raw/runs.csv`

### Results analysis

- [Results analyzer](https://github.com/maxymfarenyk/tracing-tax/blob/main/analysis/analyze.py): `analysis/analyze.py`
- [Summaries and charts](https://github.com/maxymfarenyk/tracing-tax/tree/main/results/analysis): `results/analysis`

### Other components

- **Locust load**
- **Redis**

## Connections

- Locust load → Gateway: sends requests (evidence: `README.md`)
- Load profile → Gateway: targets (evidence: `README.md`)
- Gateway → HTTP client helper: calls (evidence: `services/gateway/app.py`)
- HTTP client helper → Orders: HTTP request (evidence: `services/orders/app.py`)
- Orders → HTTP client helper: calls (evidence: `services/orders/app.py`)
- HTTP client helper → Inventory: HTTP request
- HTTP client helper → Payments: HTTP request
- Inventory → Redis: increments stock (evidence: `services/inventory/app.py`)
- Gateway → Fault injection: injects faults (evidence: `services/gateway/app.py`)
- Orders → Fault injection: injects faults (evidence: `services/orders/app.py`)
- Inventory → Fault injection: injects faults (evidence: `services/inventory/app.py`)
- Payments → Fault injection: injects faults (evidence: `services/payments/app.py`)
- Sampling scenarios → OTel Collector: selects configuration (evidence: `README.md`)
- Sampling scenarios → Adaptive sampler: enables strategy (evidence: `README.md`)
- Gateway → OTel Collector: exports traces (evidence: `README.md`)
- Orders → OTel Collector: exports traces (evidence: `README.md`)
- Inventory → OTel Collector: exports traces (evidence: `README.md`)
- Payments → OTel Collector: exports traces (evidence: `README.md`)
- OTel Collector → Jaeger: exports traces (evidence: `README.md`)
- cAdvisor → Prometheus: provides metrics (evidence: `README.md`)
- OTel Collector → Prometheus: exposes metrics (evidence: `README.md`)
- Prometheus → Grafana: supplies dashboards (evidence: `README.md`)
- Experiment runner → Load profile: runs load (evidence: `scripts/run_experiment.py`)
- Experiment runner → Prometheus: queries metrics (evidence: `scripts/run_experiment.py`)
- Experiment runner → Jaeger: queries traces (evidence: `scripts/run_experiment.py`)
- Experiment runner → Run dataset: writes rows (evidence: `README.md`)
- Results analyzer → Run dataset: reads runs (evidence: `analysis/analyze.py`)
- Results analyzer → Summaries and charts: writes reports (evidence: `analysis/analyze.py`)
- Trace verification → Gateway: sends request (evidence: `scripts/verify_trace.py`)
- Trace verification → Jaeger: queries trace (evidence: `scripts/verify_trace.py`)
- Monitoring verification → Gateway: sends requests (evidence: `scripts/verify_monitoring.py`)
- Monitoring verification → Prometheus: checks metrics (evidence: `scripts/verify_monitoring.py`)
- Sampling verification → Gateway: sends requests (evidence: `scripts/verify_sampling.py`)
- Sampling verification → Monitoring verification: uses query helpers (evidence: `scripts/verify_sampling.py`)
- Sampling verification → Sampling scenarios: reads settings (evidence: `scripts/verify_sampling.py`)
