Skip to content

Commit e8e19b6

Browse files
Copilotlalitb
Copilot
and
lalitb
authored
[Copilot] Add instructions for OpenTelemetry C++ (open-telemetry#3614)
* Initial plan * Add comprehensive GitHub Copilot instructions for OpenTelemetry C++ Co-authored-by: lalitb <[email protected]> * Emphasize maintainer mode validation in GitHub Copilot instructions Co-authored-by: lalitb <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: lalitb <[email protected]> Co-authored-by: Lalit Kumar Bhasin <[email protected]>
1 parent f813f86 commit e8e19b6

File tree

1 file changed

+302
-0
lines changed

1 file changed

+302
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# OpenTelemetry C++
2+
3+
OpenTelemetry C++ is a comprehensive telemetry SDK providing APIs and
4+
implementations for traces, metrics, and logs. It supports both CMake and Bazel
5+
build systems and runs on Linux, macOS, and Windows with modern C++ compilers
6+
(C++14/17/20).
7+
8+
Always reference these instructions first and fallback to search or bash
9+
commands only when you encounter unexpected information that does not match the
10+
info here.
11+
12+
## Working Effectively
13+
14+
### Bootstrap, Build, and Test the Repository
15+
16+
**CRITICAL: NEVER CANCEL builds or long-running commands. Set appropriate
17+
timeouts.**
18+
19+
#### CMake Build (Recommended for Development)
20+
21+
```bash
22+
# Install basic dependencies (Ubuntu/Debian)
23+
sudo apt-get update
24+
sudo apt-get install -y build-essential cmake git pkg-config
25+
26+
# Configure CMake build
27+
mkdir -p build && cd build
28+
cmake ..
29+
# Takes ~12 seconds. Always completes quickly.
30+
31+
# Build the project
32+
make -j$(nproc)
33+
# Takes ~3 minutes. NEVER CANCEL. Set timeout to 15+ minutes.
34+
35+
# Run all tests
36+
ctest --output-on-failure
37+
# Takes ~24 seconds. Set timeout to 5+ minutes.
38+
```
39+
40+
#### CI Build (Full Validation)
41+
42+
```bash
43+
# Run the full CI validation (includes additional exporters)
44+
./ci/do_ci.sh cmake.test
45+
# Takes ~5.2 minutes. NEVER CANCEL. Set timeout to 20+ minutes.
46+
```
47+
48+
#### Bazel Build (Alternative)
49+
50+
```bash
51+
# Install bazelisk (managed Bazel)
52+
sudo ./ci/install_bazelisk.sh
53+
54+
# Build simple example
55+
bazel build //examples/simple:example_simple
56+
# Time varies. NEVER CANCEL. Set timeout to 15+ minutes.
57+
58+
# Run simple example
59+
bazel-bin/examples/simple/example_simple
60+
```
61+
62+
**Note**: Bazel may have network connectivity issues in some environments when
63+
downloading the required Bazel version (7.1.1).
64+
65+
### Validation
66+
67+
Always validate your changes using these steps after making code modifications:
68+
69+
#### Core Validation Scenario
70+
71+
```bash
72+
# 1. Build and test successfully
73+
cd build && make -j$(nproc) && ctest --output-on-failure
74+
75+
# 2. Run a simple example to verify functionality
76+
./examples/simple/example_simple
77+
# Should output telemetry spans with service.name, trace_id, span_id
78+
79+
# 3. Format code properly
80+
./tools/format.sh
81+
# Takes ~30 seconds. Must complete without errors.
82+
83+
# 4. Validate with maintainer mode (CRITICAL for warnings)
84+
./ci/do_ci.sh cmake.maintainer.sync.test
85+
# Takes ~4-6 minutes. NEVER CANCEL. Ensures all warnings are resolved.
86+
```
87+
88+
#### Required Tools for Formatting
89+
90+
```bash
91+
# Install formatting dependencies
92+
pip install cmake_format # For CMake files
93+
go install github.com/bazelbuild/buildtools/buildifier@latest # For Bazel files
94+
# clang-format should already be available on most systems
95+
```
96+
97+
### Maintainer Mode Validation
98+
99+
**CRITICAL**: Always run maintainer mode builds to ensure warning-free code:
100+
101+
```bash
102+
# Run maintainer mode validation
103+
./ci/do_ci.sh cmake.maintainer.sync.test
104+
105+
# What this does:
106+
# - Enables -Wall -Werror -Wextra compiler flags
107+
# - Treats all warnings as errors
108+
# - Ensures strict code quality standards
109+
# - Required for all contributions
110+
```
111+
112+
Maintainer mode (`-DOTELCPP_MAINTAINER_MODE=ON`) is essential for catching potential issues that would cause CI failures. It enables the strictest warning levels and treats warnings as compilation errors.
113+
114+
### CI Integration
115+
116+
Always run these before committing to ensure CI will pass:
117+
118+
```bash
119+
# Format all code
120+
./tools/format.sh
121+
122+
# Run linting (if shellcheck available for shell scripts)
123+
shellcheck --severity=error ci/*.sh
124+
125+
# CRITICAL: Validate with maintainer mode to catch all warnings
126+
./ci/do_ci.sh cmake.maintainer.sync.test
127+
# Takes ~4-6 minutes. Enables -Wall -Werror -Wextra for strict validation.
128+
129+
# Validate build with additional exporters
130+
./ci/do_ci.sh cmake.test
131+
```
132+
133+
## Common Tasks
134+
135+
### Building and Running Examples
136+
137+
Examples demonstrate OpenTelemetry functionality and validate your environment:
138+
139+
```bash
140+
# Build and run simple tracing example
141+
cd build
142+
make example_simple
143+
./examples/simple/example_simple
144+
145+
# Build and run logs example
146+
make logs_simple_example
147+
./examples/logs_simple/logs_simple_example
148+
149+
# Build and run batch processing example
150+
make batch_example
151+
./examples/batch/batch_example
152+
```
153+
154+
### Testing Changes
155+
156+
```bash
157+
# Run specific test groups
158+
ctest -R trace # Run only trace tests
159+
ctest -R metrics # Run only metrics tests
160+
ctest -R logs # Run only logs tests
161+
162+
# Run tests with verbose output for debugging
163+
ctest --verbose --output-on-failure
164+
165+
# Run a specific test by name
166+
ctest -R "trace.SystemTimestampTest.Construction" --verbose
167+
```
168+
169+
### Key Directories and Navigation
170+
171+
```text
172+
api/ - Public OpenTelemetry API headers
173+
sdk/ - SDK implementation (most business logic)
174+
exporters/ - Output plugins (ostream, memory, etc.)
175+
examples/ - Sample applications demonstrating usage
176+
├── simple/ - Basic tracing example (start here)
177+
├── logs_simple/ - Basic logging example
178+
├── metrics_simple/ - Basic metrics example (may be disabled)
179+
└── batch/ - Batch processing example
180+
ci/ - CI scripts and build automation
181+
tools/ - Development tools (formatting, etc.)
182+
test_common/ - Shared test utilities
183+
third_party/ - External dependencies
184+
```
185+
186+
### Important Files
187+
188+
- `CMakeLists.txt` - Main CMake configuration
189+
- `WORKSPACE` - Bazel workspace configuration
190+
- `third_party_release` - Dependency version specifications
191+
- `ci/do_ci.sh` - Main CI script with build targets
192+
- `tools/format.sh` - Code formatting script
193+
- `.github/workflows/ci.yml` - GitHub Actions CI configuration
194+
195+
## Build Targets and Options
196+
197+
### CI Script Targets (./ci/do_ci.sh)
198+
199+
```bash
200+
cmake.test # Standard CMake build with exporters (~5.2 min)
201+
cmake.maintainer.sync.test # Maintainer mode: -Wall -Werror -Wextra (~4-6 min)
202+
cmake.maintainer.async.test # Maintainer mode with async export enabled
203+
cmake.maintainer.cpp11.async.test # Maintainer mode with C++11
204+
cmake.maintainer.abiv2.test # Maintainer mode with ABI v2
205+
cmake.legacy.test # GCC 4.8 compatibility testing
206+
cmake.c++20.test # C++20 standard testing
207+
bazel.test # Standard Bazel build and test
208+
format # Run formatting tools
209+
code.coverage # Build with coverage analysis
210+
```
211+
212+
### CMake Configuration Options
213+
214+
Key options you can pass to `cmake ..`:
215+
216+
```bash
217+
-DWITH_EXAMPLES=ON # Build examples (default ON)
218+
-DWITH_PROMETHEUS=ON # Enable Prometheus exporter
219+
-DWITH_ZIPKIN=ON # Enable Zipkin exporter
220+
-DWITH_OTLP_GRPC=ON # Enable OTLP gRPC exporter
221+
-DWITH_OTLP_HTTP=ON # Enable OTLP HTTP exporter
222+
-DBUILD_TESTING=ON # Build tests (default ON)
223+
-DCMAKE_BUILD_TYPE=Debug # Debug build
224+
```
225+
226+
## Timing Expectations
227+
228+
**CRITICAL**: These are measured times. Always set longer timeouts to prevent
229+
premature cancellation.
230+
231+
| Operation | Measured Time | Recommended Timeout |
232+
|-----------|---------------|-------------------|
233+
| CMake configure | 12 seconds | 2 minutes |
234+
| CMake build (parallel) | 3 minutes | 15 minutes |
235+
| Test execution (ctest) | 24 seconds | 5 minutes |
236+
| CI cmake.test | 5.2 minutes | 20 minutes |
237+
| CI cmake.maintainer.sync.test | 4-6 minutes | 20 minutes |
238+
| Format script | 17 seconds | 2 minutes |
239+
| Bazel build | Varies | 15+ minutes |
240+
241+
**NEVER CANCEL** any build or test operation. Build systems may appear to hang
242+
but are typically downloading dependencies or performing intensive compilation.
243+
244+
## Troubleshooting
245+
246+
### Common Issues
247+
248+
**Build Fails**:
249+
250+
- Ensure all dependencies installed:
251+
`sudo apt-get install build-essential cmake git pkg-config`
252+
- Clean build directory: `rm -rf build && mkdir build`
253+
254+
**Tests Fail**:
255+
256+
- Set `CTEST_OUTPUT_ON_FAILURE=1` for detailed test output
257+
- Run specific failing test: `ctest -R <test_name> --verbose`
258+
259+
**Format Script Fails**:
260+
261+
- Install missing tools: `pip install cmake_format` and buildifier via Go
262+
- Check clang-format version: should be 14+ (18+ preferred)
263+
264+
**Bazel Issues**:
265+
266+
- Network connectivity may prevent Bazel version download
267+
- Use CMake as primary build system for development
268+
- Check `.bazelversion` file for required version (7.1.1)
269+
270+
### Network/Connectivity Issues
271+
272+
Some tools require internet access:
273+
274+
- Bazel downloading specific version
275+
- Third-party dependencies during first build
276+
- CI scripts pulling Docker images for benchmarks
277+
278+
For offline development, use CMake with pre-installed dependencies.
279+
280+
## Repository Structure Summary
281+
282+
**Core Components**:
283+
284+
- **API**: Header-only library in `api/` for instrumentation
285+
- **SDK**: Implementation in `sdk/` with resource detection, processors, exporters
286+
- **Exporters**: Output backends in `exporters/` (console, memory, Prometheus, etc.)
287+
288+
**Development Workflow**:
289+
290+
1. Make changes to relevant component
291+
2. Build and test: `cd build && make -j$(nproc) && ctest`
292+
3. Run example: `./examples/simple/example_simple`
293+
4. Format code: `./tools/format.sh`
294+
5. Validate warnings: `./ci/do_ci.sh cmake.maintainer.sync.test`
295+
6. Final validation: `./ci/do_ci.sh cmake.test`
296+
297+
**Key Standards**:
298+
299+
- C++14 minimum, C++17/20 supported
300+
- Google C++ Style Guide for naming
301+
- Automatic formatting via clang-format
302+
- Comprehensive test coverage with GoogleTest

0 commit comments

Comments
 (0)