Skip to content

Commit 70ac4b3

Browse files
thu-gytthu-gyt
committed
add tags docs
1 parent 049ce53 commit 70ac4b3

2 files changed

Lines changed: 167 additions & 4 deletions

File tree

‎docs/src/SUMMARY.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,9 @@
2525
- [BookInfo](./user-guide/workloads/bookinfo.md)
2626
- [Social Network](./user-guide/workloads/social-network.md)
2727
- [Trace Analysis](./user-guide/trace-analysis.md)
28-
- [Web UI](./user-guide/web-ui.md)
28+
- [Web Interface](./user-guide/web-interface.md)
2929
- [Database Management](./user-guide/database.md)
30+
- [Tags](./user-guide/tags.md)
3031

3132
---
3233

@@ -35,6 +36,8 @@
3536
- [System Overview](./architecture/overview.md)
3637
- [Agent Architecture](./architecture/agent.md)
3738
- [Server Architecture](./architecture/server.md)
39+
- [Data Flow](./architecture/data-flow.md)
40+
- [Protocol Support](./architecture/protocols.md)
3841

3942
---
4043

@@ -44,6 +47,7 @@
4447
- [System Hooks](./ebpf/hooks.md)
4548
- [Data Structures](./ebpf/structures.md)
4649
- [Memory Maps](./ebpf/maps.md)
50+
- [Performance Analysis](./ebpf/performance.md)
4751

4852
---
4953

@@ -55,14 +59,14 @@
5559
- [Performance Tuning](./advanced/performance-tuning.md)
5660
- [Monitoring & Observability](./advanced/monitoring.md)
5761

58-
<!-- --- -->
62+
---
5963

60-
<!-- # API Reference
64+
# API Reference
6165

6266
- [Agent API](./api/agent.md)
6367
- [Server API](./api/server.md)
6468
- [Configuration Schema](./api/configuration.md)
65-
- [Data Formats](./api/data-formats.md) -->
69+
- [Data Formats](./api/data-formats.md)
6670

6771
---
6872

‎docs/src/user-guide/tags.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
2+
# Container Tagging Module
3+
4+
This module provides functionality for collecting and caching container metadata (Docker and Kubernetes) for processes traced by eBPF. It's part of a distributed tracing system that enriches spans with container information.
5+
6+
## Overview
7+
8+
The module maintains thread-local caches of container metadata keyed by TGID (Thread Group ID) and provides methods to retrieve this information. It supports both Docker containers and Kubernetes pods.
9+
10+
## Thread-Local Caches
11+
12+
### Docker Cache
13+
```rust
14+
thread_local! {
15+
static TGID_DOCKER_MAP: RefCell<HashMap<u32, DockerTag>> = RefCell::new(HashMap::new());
16+
}
17+
```
18+
Caches Docker container metadata to avoid repeated API calls.
19+
20+
### Kubernetes Cache
21+
```rust
22+
thread_local! {
23+
static TGID_K8S_MAP: RefCell<HashMap<u32, K8sTag>> = RefCell::new(HashMap::new());
24+
}
25+
```
26+
Caches Kubernetes pod metadata to avoid repeated CLI calls.
27+
28+
## Data Structures
29+
30+
### DockerTag
31+
Represents Docker container metadata.
32+
33+
**Fields:**
34+
- `container_id`: String - Docker container ID
35+
- `container_name`: String - Name of the container
36+
- `image`: String - Docker image used
37+
- `hostname`: String - Container hostname
38+
- `gateway`: String - Network gateway
39+
- `tgid`: u32 - Thread Group ID
40+
- `ip`: String - Container IP address
41+
- `network_mode`: String - Docker network mode
42+
- `created`: String - Creation timestamp
43+
44+
**Methods:**
45+
46+
#### `get_docker_tags(tgid: u32) -> Option<DockerTag>`
47+
Retrieves Docker metadata for a given TGID.
48+
49+
**Workflow:**
50+
1. Checks thread-local cache first
51+
2. If not cached, connects to Docker daemon
52+
3. Lists all containers and inspects each
53+
4. Maps container PIDs to TGIDs using `docker top`
54+
5. Caches results for all PIDs in the container
55+
6. Returns cached entry if available
56+
57+
**Returns:** `Some(DockerTag)` if found, `None` otherwise
58+
59+
### K8sTag
60+
Represents Kubernetes pod metadata.
61+
62+
**Fields:**
63+
- `tgid`: u32 - Thread Group ID
64+
- `name`: String - Pod name
65+
- `state`: String - Pod state
66+
- `created_at`: String - Creation timestamp
67+
- `image`: String - Container image
68+
- `namespace`: String - Kubernetes namespace
69+
- `cpu_period`: String - CPU period limit
70+
- `cpu_shares`: String - CPU shares
71+
72+
**Methods:**
73+
74+
#### `get_k8s_tags(tgid: u32) -> Option<K8sTag>`
75+
Retrieves Kubernetes metadata for a given TGID.
76+
77+
**Workflow:**
78+
1. Checks thread-local cache first
79+
2. If not cached, uses `crictl` CLI to list containers
80+
3. Inspects each container with `crictl inspect`
81+
4. Extracts PID and metadata from JSON output
82+
5. Caches the result
83+
6. Returns cached entry if found
84+
85+
**Returns:** `Some(K8sTag)` if found, `None` otherwise
86+
87+
### EbpfTag
88+
Represents eBPF tracing metadata from network events.
89+
90+
**Fields:**
91+
- `tgid`: u32 - Thread Group ID
92+
- `pid`: u32 - Process ID
93+
- `component`: String - Process name (from comm field)
94+
- `direction`: Direction - Traffic direction (Ingress/Egress)
95+
- `protocol`: L7Protocol - Application layer protocol
96+
- `src_ip`: String - Source IP address
97+
- `dst_ip`: String - Destination IP address
98+
- `src_port`: u16 - Source port
99+
- `dst_port`: u16 - Destination port
100+
- `req_seq`: u32 - Request sequence number
101+
- `resp_seq`: u32 - Response sequence number
102+
103+
### SpanTag
104+
Aggregate structure containing all tagging information for a span.
105+
106+
**Fields:**
107+
- `ebpf_tag`: EbpfTag - eBPF tracing metadata
108+
- `docker_tag`: Option<DockerTag> - Optional Docker metadata
109+
- `k8s_tag`: Option<K8sTag> - Optional Kubernetes metadata
110+
- `other_tags`: HashMap<String, String> - Additional tags (e.g., user)
111+
112+
**Methods:**
113+
114+
#### `set_tags(req: &Message, resp: &Message) -> SpanTag`
115+
Creates a complete SpanTag from request and response messages.
116+
117+
**Workflow:**
118+
1. Extracts network quintuple information based on direction
119+
2. Creates `EbpfTag` from message data
120+
3. Attempts to fetch Docker and Kubernetes metadata asynchronously
121+
4. Adds additional tags from agent configuration
122+
5. Returns populated `SpanTag`
123+
124+
## Helper Functions
125+
126+
### `u32_to_ip(ip: u32) -> String`
127+
Converts a 32-bit integer to IPv4 address string.
128+
129+
## Usage Example
130+
131+
```rust
132+
let span_tag = SpanTag::set_tags(&request_message, &response_message).await;
133+
134+
// Access different tag types
135+
if let Some(docker_tag) = &span_tag.docker_tag {
136+
println!("Container: {}", docker_tag.container_name);
137+
}
138+
139+
if let Some(k8s_tag) = &span_tag.k8s_tag {
140+
println!("Pod: {} in namespace {}", k8s_tag.name, k8s_tag.namespace);
141+
}
142+
```
143+
144+
## Dependencies
145+
146+
- `arc_swap`: For atomic configuration access
147+
- `bollard`: Docker client library
148+
- `observ_config`: Configuration management
149+
- `observ_trace_common`: Common tracing types
150+
- `serde`: Serialization/deserialization
151+
- `std`: Standard library components
152+
153+
## Notes
154+
155+
- Thread-local caching improves performance but limits cache sharing across threads
156+
- Docker integration requires access to Docker daemon
157+
- Kubernetes integration relies on `crictl` CLI tool being available
158+
- Network address conversion assumes IPv4 addresses
159+
- All async methods should be awaited in async contexts

0 commit comments

Comments
 (0)