You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When unsure about implementation details, ALWAYS ask the developer.
15
+
16
+
## Project Context
17
+
`dd-trace-py` is the official Datadog library for tracing and monitoring Python applications. It provides developers with deep visibility into their application's performance by enabling distributed tracing, continuous profiling, and error tracking.
18
+
19
+
The library offers automatic instrumentation for a wide variety of popular Python frameworks and libraries, such as Django, Flask, Celery, and SQLAlchemy. This allows for quick setup and immediate insights with minimal code changes. For more specific use cases, `dd-trace-py` also provides a comprehensive manual instrumentation API.
20
+
21
+
Key features include:
22
+
- **Distributed Tracing:** Trace requests across service boundaries to understand the full lifecycle of a request in a microservices architecture.
23
+
- **Continuous Profiling:** Analyze code-level performance in production to identify and optimize CPU and memory-intensive operations.
24
+
- **Error Tracking:** Capture and aggregate unhandled exceptions and errors, linking them to specific traces for easier debugging.
25
+
- **Application Security Monitoring (ASM):** Detect and protect against threats and vulnerabilities within your application.
26
+
27
+
## Critical Architecture Decisions
28
+
29
+
### Automatic Instrumentation via Monkey-Patching
30
+
`dd-trace-py` heavily relies on monkey-patching for its automatic instrumentation. This allows the library to trace a wide range of standard libraries and frameworks without requiring any code changes from the user. This is a powerful feature that makes the library easy to adopt, but it's also a critical piece of architecture to be aware of when debugging or extending the tracer.
31
+
32
+
### Performance First
33
+
The tracer is designed to run in high-throughput production environments. This means performance is a primary concern. Key decisions to achieve this include:
34
+
1. **Core components written in C/Cython:** For performance-critical code paths.
35
+
2. **Low-overhead sampling:** To reduce the performance impact of tracing.
36
+
3. **Efficient serialization:** Using `msgpack` to communicate with the Datadog Agent.
37
+
38
+
### Extensible Integrations
39
+
The library is designed to be easily extensible with new "integrations" for libraries that are not yet supported. The integration system provides a clear pattern for adding new instrumentation.
40
+
41
+
### Configuration via Environment Variables
42
+
To make it easy to configure the tracer in various environments (local development, CI, production containers, etc.), the primary method of configuration is through environment variables.
43
+
44
+
## Code Style and Patterns
45
+
46
+
### Anchor comments
47
+
48
+
Add specially formatted comments throughout the codebase, where appropriate, for yourself as inline knowledge that can be easily `grep`ped for.
49
+
50
+
### Guidelines:
51
+
52
+
- Use `AIDEV-NOTE:`, `AIDEV-TODO:`, or `AIDEV-QUESTION:` (all-caps prefix) for comments aimed at AI and developers.
53
+
- **Important:** Before scanning files, always first try to **grep for existing anchors** `AIDEV-*` in relevant subdirectories.
54
+
- **Update relevant anchors** when modifying associated code.
55
+
- **Do not remove `AIDEV-NOTE`s** without explicit human instruction.
56
+
- Make sure to add relevant anchor comments, whenever a file or piece of code is:
57
+
* too complex, or
58
+
* very important, or
59
+
* confusing, or
60
+
* could have a bug
61
+
62
+
## Domain Glossary
63
+
64
+
- **Trace**: A representation of a single request or transaction as it moves through a system. It's composed of one or more spans.
65
+
- **Span**: The basic building block of a trace. It represents a single unit of work (e.g., a function call, a database query). Spans have a start and end time, a name, a service, a resource, and can contain metadata (tags).
66
+
- **Name (`span.name`)**: A string that represents the name of the operation being measured. It should be a general, human-readable identifier for the type of operation, such as `http.request`, `sqlalchemy.query`, or a function name like `auth.login`. This is typically more general than the `resource` name.
67
+
- **Service**: A logical grouping of traces that perform the same function. For example, a web application or a database.
68
+
- **Resource**: The specific operation being performed within a service that a span represents. For example, a web endpoint (`/users/{id}`) or a database query (`SELECT * FROM users`).
69
+
- **Instrumentation**: The process of adding code to an application to generate traces. This can be done automatically by the library (`ddtrace-run`) or manually using the tracer API.
70
+
- **Integration**: A component of `dd-trace-py` that provides automatic instrumentation for a specific library or framework (e.g., Django, `requests`, `psycopg2`).
71
+
- **Tracer**: The object that creates and manages spans. It's the main entry point for manual instrumentation.
72
+
- **Profiler**: A component that collects data on CPU and memory usage at the code level, helping to identify performance bottlenecks.
73
+
- **`ddtrace-run`**: A command-line utility that automatically instruments a Python application by monkey-patching supported libraries at runtime.
74
+
- **Tag**: A key-value pair of metadata that can be added to a span to provide additional context for filtering, grouping, or analysis.
75
+
76
+
## What AI Must NEVER Do
77
+
78
+
1. **Never change public API contracts** - Breaks real applications
79
+
2. **Never commit secrets** - Use environment variables
80
+
3. **Never assume business logic** - Always ask
81
+
4. **Never remove AIDEV- comments** - They're there for a reason
│ ├── contributing-testing.rst # Testing setup and procedures
122
+
│ ├── api.rst # API reference documentation
123
+
│ └── basic_usage.rst # Getting started guide
124
+
│
125
+
├── src/ # Native code sources
126
+
│ └── native/ # C/C++ native extensions for performance
127
+
│
128
+
├── lib-injection/ # Library injection for serverless and containers
129
+
├── docker/ # Docker build configurations
130
+
├── hooks/ # Git hooks for code quality
131
+
├── ci/ # CI configuration and utilities
132
+
├── releasenotes/ # Release notes management
133
+
├── templates/ # Code generation templates
134
+
│
135
+
├── setup.py # Package build configuration
136
+
├── pyproject.toml # Modern Python project configuration
137
+
├── riotfile.py # Multi-version testing with Riot
138
+
├── hatch.toml # Hatch build system configuration
139
+
├── docker-compose.yml # Development environment setup
140
+
└── conftest.py # Global PyTest configuration
141
+
```
142
+
143
+
## Internal Implementation Details
144
+
145
+
**`internal/` folders:** Contains private methods and functionality used by the library itself. Code that is not part of the public API and not intended for direct use by customers.
146
+
147
+
## Key Components
148
+
149
+
### Core Library (`ddtrace/`)
150
+
- **Main Package**: Contains the primary tracing functionality and public APIs
151
+
- **Contrib**: 100+ integrations with popular Python libraries (Django, Flask, Redis, etc.)
152
+
- **AppSec**: Application security features including IAST and WAF protection
153
+
- **Profiling**: Continuous profiling capabilities for CPU, memory, and I/O
154
+
- **Internal**: Implementation details not part of the public API
155
+
156
+
### Testing (`tests/`)
157
+
- **Comprehensive Test Suite**: Unit tests, integration tests, and end-to-end tests
158
+
- **Snapshots**: Regression testing using captured test outputs
159
+
- **Contrib Tests**: Specific tests for each third-party integration
160
+
161
+
### Development Tools
162
+
- **Benchmarks**: Performance testing and regression detection
163
+
- **Scripts**: Development utilities and automation tools
164
+
- **Hooks**: Git hooks for code quality enforcement
165
+
- **Docker**: Containerized development and testing environments
166
+
167
+
### Build & Distribution
168
+
- **Native Code**: C/C++ extensions for performance-critical components
169
+
- **Multiple Build Systems**: Support for setuptools, hatch, and modern Python packaging
170
+
- **Release Management**: Automated release notes and versioning
171
+
172
+
### Documentation & Contributing
173
+
- **Extensive Docs**: API documentation, usage guides, and contributing guidelines
174
+
- **Templates**: Code generation templates for new integrations
175
+
- **CI/CD**: Comprehensive testing and deployment pipelines
0 commit comments