Skip to content

Commit 52ef536

Browse files
owentowent
authored
Merge branch 'main' into validate_utf8_string_in_setters
2 parents 6625f78 + 4193b21 commit 52ef536

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1087
-226
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

‎.github/workflows/benchmark.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ jobs:
1313
runs-on: ubuntu-latest
1414
steps:
1515
- name: Harden the runner (Audit all outbound calls)
16-
uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
16+
uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
1717
with:
1818
egress-policy: audit
1919

@@ -55,7 +55,7 @@ jobs:
5555
runs-on: ubuntu-latest
5656
steps:
5757
- name: Harden the runner (Audit all outbound calls)
58-
uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
58+
uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
5959
with:
6060
egress-policy: audit
6161

@@ -69,7 +69,7 @@ jobs:
6969
run: |
7070
cat benchmarks/*
7171
- name: Push benchmark result
72-
uses: benchmark-action/github-action-benchmark@d48d326b4ca9ba73ca0cd0d59f108f9e02a381c7 # v1.20.4
72+
uses: benchmark-action/github-action-benchmark@4bdcce38c94cec68da58d012ac24b7b1155efe8b # v1.20.7
7373
with:
7474
name: OpenTelemetry-cpp ${{ matrix.components }} Benchmark
7575
tool: 'googlecpp'

0 commit comments

Comments
 (0)