Skip to content

Commit 4980849

Browse files
committed
Remove copied code and line references
1 parent e18cf50 commit 4980849

File tree

1 file changed

+18
-89
lines changed

1 file changed

+18
-89
lines changed

docs/crashtracker-unix-socket-communication.md

Lines changed: 18 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,14 @@
11
# Crash Tracker Unix Socket Communication Protocol
22

3-
**Date**: September 23, 2025
3+
**Date**: September 24, 2025
44

55
## Overview
66

77
This document describes the Unix domain socket communication protocol used between the crash tracker's collector and receiver processes. The crash tracker uses a two-process architecture where the collector (a fork of the crashing process) communicates crash data to the receiver (a fork+execve process) via an anonymous Unix domain socket pair.
88

99
## Socket Creation and Setup
1010

11-
The communication channel is established using `socketpair()` to create an anonymous Unix domain socket pair:
12-
13-
```rust
14-
let (uds_parent, uds_child) = socket::socketpair(
15-
socket::AddressFamily::Unix,
16-
socket::SockType::Stream,
17-
None,
18-
socket::SockFlag::empty(),
19-
)?;
20-
```
21-
22-
**Location**: `datadog-crashtracker/src/collector/receiver_manager.rs:78-85`
11+
The communication channel is established using `socketpair()` to create an anonymous Unix domain socket pair with Unix address family and stream socket type.
2312

2413
### File Descriptor Management
2514

@@ -31,7 +20,7 @@ let (uds_parent, uds_child) = socket::socketpair(
3120

3221
### Data Format
3322

34-
The crash data is transmitted as a structured text stream with distinct sections delimited by markers defined in `datadog-crashtracker/src/shared/constants.rs`.
23+
The crash data is transmitted as a structured text stream with distinct sections delimited by predefined markers.
3524

3625
### Message Structure
3726

@@ -85,8 +74,6 @@ DD_CRASHTRACK_END_SIGINFO
8574

8675
Contains signal details extracted from `siginfo_t` structure.
8776

88-
**Implementation**: `datadog-crashtracker/src/collector/emitters.rs:223-263`
89-
9077
#### 4. Process Context Section (ucontext)
9178
```
9279
DD_CRASHTRACK_BEGIN_UCONTEXT
@@ -98,8 +85,6 @@ Contains processor state at crash time from `ucontext_t`. Format varies by platf
9885
- **Linux**: Direct debug print of `ucontext_t`
9986
- **macOS**: Includes both `ucontext_t` and machine context (`mcontext`)
10087

101-
**Implementation**: `datadog-crashtracker/src/collector/emitters.rs:190-221`
102-
10388
#### 5. Process Information Section
10489
```
10590
DD_CRASHTRACK_BEGIN_PROCINFO
@@ -154,8 +139,6 @@ DD_CRASHTRACK_END_FILE "/proc/self/maps"
154139

155140
Contains memory mapping information from `/proc/self/maps` for symbol resolution.
156141

157-
**Implementation**: `datadog-crashtracker/src/collector/emitters.rs:184-187`
158-
159142
#### 11. Stack Trace Section
160143
```
161144
DD_CRASHTRACK_BEGIN_STACKTRACE
@@ -172,8 +155,6 @@ Each line represents one stack frame. Frame format depends on symbol resolution
172155

173156
Stack frames with stack pointer less than the fault stack pointer are filtered out to exclude crash tracker frames.
174157

175-
**Implementation**: `datadog-crashtracker/src/collector/emitters.rs:45-117`
176-
177158
#### 12. Completion Marker
178159
```
179160
DD_CRASHTRACK_DONE
@@ -185,69 +166,29 @@ Indicates end of crash report transmission.
185166

186167
### 1. Collector Side (Write End)
187168

188-
**File**: `datadog-crashtracker/src/collector/collector_manager.rs:92-102`
189-
190-
```rust
191-
let mut unix_stream = unsafe { UnixStream::from_raw_fd(uds_fd) };
192-
193-
let report = emit_crashreport(
194-
&mut unix_stream,
195-
config,
196-
config_str,
197-
metadata_str,
198-
sig_info,
199-
ucontext,
200-
ppid,
201-
);
202-
```
203-
204-
The collector:
205-
1. Creates `UnixStream` from inherited file descriptor
206-
2. Calls `emit_crashreport()` to serialize and write all crash data
169+
The collector process performs the following operations:
170+
1. Creates a Unix stream from the inherited file descriptor
171+
2. Serializes and writes all crash data sections in the defined order
207172
3. Flushes the stream after each section for reliability
208-
4. Exits with `libc::_exit(0)` on completion
173+
4. Exits cleanly after completing the transmission
209174

210175
### 2. Receiver Side (Read End)
211176

212-
**File**: `datadog-crashtracker/src/receiver/entry_points.rs:97-119`
213-
214-
```rust
215-
pub(crate) async fn receiver_entry_point(
216-
timeout: Duration,
217-
stream: impl AsyncBufReadExt + std::marker::Unpin,
218-
) -> anyhow::Result<()> {
219-
if let Some((config, mut crash_info)) = receive_report_from_stream(timeout, stream).await? {
220-
// Process crash data
221-
if let Err(e) = resolve_frames(&config, &mut crash_info) {
222-
crash_info.log_messages.push(format!("Error resolving frames: {e}"));
223-
}
224-
if config.demangle_names() {
225-
if let Err(e) = crash_info.demangle_names() {
226-
crash_info.log_messages.push(format!("Error demangling names: {e}"));
227-
}
228-
}
229-
crash_info.async_upload_to_endpoint(config.endpoint()).await?;
230-
}
231-
Ok(())
232-
}
233-
```
234-
235-
The receiver:
236-
1. Reads from stdin (Unix socket via `dup2`)
237-
2. Parses the structured stream into `CrashInfo` and `CrashtrackerConfiguration`
177+
The receiver process handles crash data processing:
178+
1. Reads from stdin (Unix socket redirected via `dup2`)
179+
2. Parses the structured stream into crash information and configuration objects
238180
3. Performs symbol resolution if configured
239-
4. Uploads formatted crash report to backend
181+
4. Demangles symbol names if configured
182+
5. Uploads the formatted crash report to the configured backend endpoint
240183

241184
### 3. Stream Parsing
242185

243-
**File**: `datadog-crashtracker/src/receiver/receive_report.rs`
244-
245-
The receiver parses the stream by:
186+
The receiver parses the incoming stream by:
246187
1. Reading line-by-line with timeout protection
247188
2. Matching delimiter patterns to identify sections
248189
3. Accumulating section data between delimiters
249190
4. Deserializing JSON sections into appropriate data structures
250-
5. Handling the `DD_CRASHTRACK_DONE` completion marker
191+
5. Handling the completion marker to detect end of transmission
251192

252193
## Error Handling and Reliability
253194

@@ -262,11 +203,9 @@ The receiver parses the stream by:
262203
- Prevents hanging on incomplete/corrupted streams
263204

264205
### Process Cleanup
265-
- Parent process uses `wait_for_pollhup()` to detect socket closure
266-
- Kills child processes with `SIGKILL` if needed
267-
- Reaps zombie processes to prevent resource leaks
268-
269-
**File**: `datadog-crashtracker/src/collector/process_handle.rs:19-40`
206+
- Parent process detects socket closure to monitor child completion
207+
- Terminates unresponsive child processes when necessary
208+
- Properly reaps zombie processes to prevent resource leaks
270209

271210
### Data Integrity
272211
- Each section is flushed immediately after writing
@@ -276,17 +215,7 @@ The receiver parses the stream by:
276215
## Alternative Communication Modes
277216

278217
### Named Socket Mode
279-
When `unix_socket_path` is configured, the collector connects to an existing Unix socket instead of using the fork+execve receiver:
280-
281-
```rust
282-
let receiver = if unix_socket_path.is_empty() {
283-
Receiver::spawn_from_stored_config()? // Fork+execve mode
284-
} else {
285-
Receiver::from_socket(unix_socket_path)? // Named socket mode
286-
};
287-
```
288-
289-
This allows integration with long-lived receiver processes.
218+
When a Unix socket path is configured, the collector connects to an existing Unix socket instead of using the fork+execve receiver. This allows integration with long-lived receiver processes that can handle multiple crash reports.
290219

291220
**Linux Abstract Sockets**: On Linux, socket paths not starting with `.` or `/` are treated as abstract socket names.
292221

0 commit comments

Comments
 (0)