|
| 1 | +# OpenTelemetry Rust Copilot Instructions |
| 2 | + |
| 3 | +This repository contains the OpenTelemetry implementation for Rust. When working with this codebase, please follow these guidelines: |
| 4 | + |
| 5 | +## Development Tools and Commands |
| 6 | + |
| 7 | +1. **Use clippy, rustfmt, and cargo check regularly.** |
| 8 | + - Run `cargo clippy --workspace --all-targets --all-features` for comprehensive linting |
| 9 | + - Run `cargo fmt --all` to format code consistently |
| 10 | + - Run `cargo check --workspace` to verify compilation |
| 11 | + |
| 12 | +2. **Use the provided development scripts:** |
| 13 | + - Run `./scripts/precommit.sh` before committing (runs format, lint, and test) |
| 14 | + - Run `./scripts/lint.sh` for comprehensive linting across all features |
| 15 | + - Run `./scripts/test.sh` for running tests |
| 16 | + |
| 17 | +## Workspace Structure |
| 18 | + |
| 19 | +This is a Cargo workspace containing multiple crates: |
| 20 | +- `opentelemetry` - Core API crate |
| 21 | +- `opentelemetry-sdk` - SDK implementation |
| 22 | +- `opentelemetry-otlp` - OTLP exporter |
| 23 | +- `opentelemetry-stdout` - Stdout exporter |
| 24 | +- And many more specialized crates |
| 25 | + |
| 26 | +When making changes, consider the impact across the entire workspace. |
| 27 | + |
| 28 | +## Feature Flags and Compilation |
| 29 | + |
| 30 | +- This codebase uses extensive feature flags for signals (`traces`, `metrics`, `logs`) |
| 31 | +- Experimental features are behind the `otel_unstable` feature flag |
| 32 | +- Use `cargo hack --each-feature` to test across feature combinations |
| 33 | +- Some crates like `opentelemetry-prometheus` are outside the main workspace |
| 34 | + |
| 35 | +## Code Standards |
| 36 | + |
| 37 | +- **MSRV**: Minimum Supported Rust Version is 1.75 |
| 38 | +- **Error Handling**: Wrap errors in signal-specific types (`TraceError`, `MetricError`, `LogsError`) |
| 39 | +- **Commits**: Use conventional commit format (e.g., `feat:`, `fix:`, `docs:`) |
| 40 | +- **Testing**: Run `cargo test --workspace` for comprehensive testing |
| 41 | +- **Documentation**: Include examples in documentation and maintain README files |
| 42 | + |
| 43 | +## OpenTelemetry Specifics |
| 44 | + |
| 45 | +- Follow the OpenTelemetry specification |
| 46 | +- Prioritize functionality over structural compliance with spec |
| 47 | +- Use Rust idioms rather than forcing spec API patterns |
| 48 | +- Configuration priority: Environment variables > compile-time config |
| 49 | +- Use `#[cfg(feature = "otel_unstable")]` for experimental features |
| 50 | + |
| 51 | +## Build Requirements |
| 52 | + |
| 53 | +- For `opentelemetry-otlp`: Requires `protoc` (Protocol Buffers compiler) |
| 54 | +- Clone with submodules: `git clone --recurse-submodule` |
| 55 | +- Set `PROTOC` environment variable if needed: `export PROTOC=$(which protoc)` |
| 56 | + |
| 57 | +## Testing and Validation |
| 58 | + |
| 59 | +- Run benchmarks with `cargo bench` for performance-sensitive changes |
| 60 | +- Test examples in the `examples/` directory to ensure they work |
| 61 | +- Validate changes don't break existing behavior across workspace |
| 62 | +- Consider impact on different runtime features (`rt-tokio`, etc.) |
0 commit comments