# instana/python-sensor architecture

> Architecture diagram of the GitHub repository instana/python-sensor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/instana/python-sensor
- Repository: https://github.com/instana/python-sensor

## Overview

Instana is a Python application sensor for collecting metrics and distributed traces. Applications activate it by importing the package or through automatic bootstrap; framework and library instrumentation creates spans and propagates trace context, while the selected runtime agent and collector report telemetry to the Instana host agent. The package also includes runtime-specific agents, cloud/container collectors, and automatic profiling. Relationships are limited to README statements, excerpts, and SOURCE INDEX references; unsampled modules are represented only where the tree or index supports their role.

Main entry points: [`src/instana/tracer.py`](https://github.com/instana/python-sensor/blob/main/src/instana/tracer.py) (Tracer), [`src/instana/singletons.py`](https://github.com/instana/python-sensor/blob/main/src/instana/singletons.py) (Runtime selection), [`src/instana/instrumentation`](https://github.com/instana/python-sensor/tree/main/src/instana/instrumentation) (Framework hooks), [`src/instana/agent/host.py`](https://github.com/instana/python-sensor/blob/main/src/instana/agent/host.py) (Host agent client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_instrumentation["Instrumentation"]
  node_framework_hooks["Framework hooks"]
  node_library_hooks["Library hooks"]
  node_trace_utils["Trace utilities<br/>[traceutils.py]"]
end

subgraph group_tracing["Tracing Core"]
  node_tracer["Tracer<br/>[tracer.py]"]
  node_spans["Span model<br/>[span.py]"]
  node_propagators["Context propagation"]
  node_recorder["Span recorder<br/>[recorder.py]"]
end

subgraph group_collection["Collection and Reporting"]
  node_runtime_selection["Runtime selection<br/>[singletons.py]"]
  node_agent["Runtime agent"]
  node_host_agent["Host agent client<br/>[host.py]"]
  node_collector["Telemetry collector<br/>[base.py]"]
  node_cloud_collectors["Cloud collectors"]
  node_agent_base["Agent base<br/>[base.py]"]
end

subgraph group_profiling["Profiling"]
  node_profiler["Automatic profiler<br/>[profiler.py]"]
  node_profile_sampling["Profile sampling"]
end

node_application(("Python application"))
node_instana_service(("Instana host agent"))

node_application -->|"activates instrumentation"| node_framework_hooks
node_application -->|"activates instrumentation"| node_library_hooks
node_framework_hooks -->|"starts spans"| node_tracer
node_library_hooks -->|"uses tracing helpers"| node_trace_utils
node_framework_hooks -->|"extracts context"| node_propagators
node_library_hooks -->|"injects context"| node_propagators
node_trace_utils -->|"gets tracer"| node_tracer
node_tracer -.->|"creates spans"| node_spans
node_spans -->|"records spans"| node_recorder
node_runtime_selection -->|"initializes tracer"| node_tracer
node_runtime_selection -->|"selects agent"| node_agent
node_runtime_selection -->|"initializes profiler"| node_profiler
node_agent -->|"uses base agent"| node_agent_base
node_agent_base -->|"starts collector"| node_collector
node_collector -.->|"delegates reporting"| node_host_agent
node_host_agent -->|"reports telemetry"| node_instana_service
node_cloud_collectors -->|"extends collection"| node_collector
node_profiler -.->|"schedules sampling"| node_profile_sampling
node_host_agent -->|"reports metrics"| node_instana_service

click node_framework_hooks "https://github.com/instana/python-sensor/tree/main/src/instana/instrumentation"
click node_library_hooks "https://github.com/instana/python-sensor/tree/main/src/instana/instrumentation"
click node_trace_utils "https://github.com/instana/python-sensor/blob/main/src/instana/util/traceutils.py"
click node_tracer "https://github.com/instana/python-sensor/blob/main/src/instana/tracer.py"
click node_spans "https://github.com/instana/python-sensor/blob/main/src/instana/span/span.py"
click node_propagators "https://github.com/instana/python-sensor/tree/main/src/instana/propagators"
click node_recorder "https://github.com/instana/python-sensor/blob/main/src/instana/recorder.py"
click node_runtime_selection "https://github.com/instana/python-sensor/blob/main/src/instana/singletons.py"
click node_agent "https://github.com/instana/python-sensor/tree/main/src/instana/agent"
click node_host_agent "https://github.com/instana/python-sensor/blob/main/src/instana/agent/host.py"
click node_collector "https://github.com/instana/python-sensor/blob/main/src/instana/collector/base.py"
click node_cloud_collectors "https://github.com/instana/python-sensor/tree/main/src/instana/collector"
click node_profiler "https://github.com/instana/python-sensor/blob/main/src/instana/autoprofile/profiler.py"
click node_profile_sampling "https://github.com/instana/python-sensor/blob/main/src/instana/autoprofile/sampler_scheduler.py"
click node_agent_base "https://github.com/instana/python-sensor/blob/main/src/instana/agent/base.py"

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_framework_hooks,node_library_hooks,node_trace_utils toneBlue
class node_tracer,node_spans,node_propagators,node_recorder toneAmber
class node_runtime_selection,node_agent,node_host_agent,node_collector,node_cloud_collectors,node_agent_base toneMint
class node_profiler,node_profile_sampling toneRose
class node_application,node_instana_service toneIndigo
```

## Components

### Instrumentation

- [Framework hooks](https://github.com/instana/python-sensor/tree/main/src/instana/instrumentation): `src/instana/instrumentation`
- [Library hooks](https://github.com/instana/python-sensor/tree/main/src/instana/instrumentation): `src/instana/instrumentation`
- [Trace utilities](https://github.com/instana/python-sensor/blob/main/src/instana/util/traceutils.py): `src/instana/util/traceutils.py`

### Tracing Core

- [Tracer](https://github.com/instana/python-sensor/blob/main/src/instana/tracer.py): `src/instana/tracer.py`
- [Span model](https://github.com/instana/python-sensor/blob/main/src/instana/span/span.py): `src/instana/span/span.py`
- [Context propagation](https://github.com/instana/python-sensor/tree/main/src/instana/propagators): `src/instana/propagators`
- [Span recorder](https://github.com/instana/python-sensor/blob/main/src/instana/recorder.py): `src/instana/recorder.py`

### Collection and Reporting

- [Runtime selection](https://github.com/instana/python-sensor/blob/main/src/instana/singletons.py): `src/instana/singletons.py`
- [Runtime agent](https://github.com/instana/python-sensor/tree/main/src/instana/agent): `src/instana/agent`
- [Host agent client](https://github.com/instana/python-sensor/blob/main/src/instana/agent/host.py): `src/instana/agent/host.py`
- [Telemetry collector](https://github.com/instana/python-sensor/blob/main/src/instana/collector/base.py): `src/instana/collector/base.py`
- [Cloud collectors](https://github.com/instana/python-sensor/tree/main/src/instana/collector): `src/instana/collector`
- [Agent base](https://github.com/instana/python-sensor/blob/main/src/instana/agent/base.py): `src/instana/agent/base.py`

### Profiling

- [Automatic profiler](https://github.com/instana/python-sensor/blob/main/src/instana/autoprofile/profiler.py): `src/instana/autoprofile/profiler.py`
- [Profile sampling](https://github.com/instana/python-sensor/blob/main/src/instana/autoprofile/sampler_scheduler.py): `src/instana/autoprofile/sampler_scheduler.py`

### Other components

- **Python application**
- **Instana host agent**

## Connections

- Python application → Framework hooks: activates instrumentation
- Python application → Library hooks: activates instrumentation
- Framework hooks → Tracer: starts spans (evidence: `src/instana/instrumentation/aiohttp/server.py`)
- Library hooks → Trace utilities: uses tracing helpers (evidence: `src/instana/instrumentation/aiohttp/client.py`)
- Framework hooks → Context propagation: extracts context (evidence: `src/instana/instrumentation/aiohttp/server.py`)
- Library hooks → Context propagation: injects context (evidence: `src/instana/instrumentation/aiohttp/client.py`)
- Trace utilities → Tracer: gets tracer (evidence: `src/instana/util/traceutils.py`)
- Tracer → Span model: creates spans
- Span model → Span recorder: records spans (evidence: `src/instana/span/span.py`)
- Runtime selection → Tracer: initializes tracer (evidence: `src/instana/singletons.py`)
- Runtime selection → Runtime agent: selects agent (evidence: `src/instana/singletons.py`)
- Runtime selection → Automatic profiler: initializes profiler (evidence: `src/instana/singletons.py`)
- Runtime agent → Agent base: uses base agent (evidence: `src/instana/agent/host.py`)
- Agent base → Telemetry collector: starts collector (evidence: `src/instana/collector/base.py`)
- Telemetry collector → Host agent client: delegates reporting
- Host agent client → Instana host agent: reports telemetry (evidence: `src/instana/agent/host.py`)
- Cloud collectors → Telemetry collector: extends collection (evidence: `src/instana/collector/aws_fargate.py`)
- Automatic profiler → Profile sampling: schedules sampling
- Host agent client → Instana host agent: reports metrics (evidence: `src/instana/agent/host.py`)
