https://github.com/staticaland/cue-otel
https://github.com/staticaland/cue-otel
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/staticaland/cue-otel
- Owner: staticaland
- Created: 2025-06-25T13:29:22.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-25T14:18:26.000Z (12 months ago)
- Last Synced: 2026-01-19T11:38:38.072Z (5 months ago)
- Language: CUE
- Size: 14.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CUE OpenTelemetry Configuration
A minimal-but-complete OpenTelemetry Collector configuration expressed in CUE, demonstrating the "layer-cake" model for reusable configuration management.
## Overview
This project provides:
- A base OpenTelemetry Collector configuration as a CUE definition
- Environment-specific overlays (dev, prod) that extend the base
- Build tooling to generate YAML configurations
- Validation to ensure configurations are well-formed
## Structure
```
├── base.cue # Base collector definition (#Collector)
├── examples/
│ ├── dev.cue # Development overlay
│ ├── prod.cue # Production overlay
│ ├── custom-processor.cue # Custom processors example
│ └── pipeline-insertion.cue # Pipeline manipulation example
├── scripts/
│ └── build.sh # Build script
└── justfile # Build targets
```
## Usage
### Building Configurations
Generate YAML configurations from CUE files:
```bash
just build
```
This creates YAML configurations for all examples:
- `output/collector-dev.yaml` - Development configuration
- `output/collector-prod.yaml` - Production configuration
- `output/collector-custom-processor.yaml` - Custom processors example
- `output/collector-pipeline-insertion.yaml` - Pipeline manipulation example
### Validating Configurations
Validate all CUE files:
```bash
just validate
```
### Manual Commands
Export specific configurations:
```bash
# Development configuration
cue export ./examples/dev.cue -e collector -o yaml > collector-dev.yaml
# Production configuration
cue export ./examples/prod.cue -e collector -o yaml > collector-prod.yaml
# With build-time parameters
cue export ./examples/prod.cue -e collector -t build_id=$(git rev-parse --short HEAD) -o yaml
```
## Base Configuration
The base configuration (`#Collector`) includes:
- **Receivers**: OTLP (HTTP and gRPC)
- **Processors**: batch, memory_limiter
- **Exporters**: OTLP
- **Service Pipelines**: traces, metrics, logs
## Configuration Examples
### Development (`examples/dev.cue`)
- Insecure TLS connections
- Local endpoints
- Reduced batch sizes and memory limits
### Production (`examples/prod.cue`)
- Secure TLS with certificates
- Production endpoints
- API key authentication
- Optimized batch sizes and memory limits
### Custom Processors (`examples/custom-processor.cue`)
- Resource processor for adding custom attributes
- Transform processor for span modification
- Demonstrates processor insertion in traces pipeline
### Pipeline Manipulation (`examples/pipeline-insertion.cue`)
- Shows multiple approaches to modify base pipelines
- Direct processor reference by index
- List concatenation and slicing patterns
## Using as a Module
Import this base configuration in other CUE projects:
```bash
cue get pkg github.com/staticaland/cue-otel-config
```
Then use in your configurations:
```cue
package myproject
import "github.com/staticaland/cue-otel-config"
collector: otel.#Collector & {
exporters: {
otlp: {
endpoint: "my-custom-endpoint:4317"
}
}
}
```
## CUE Features Demonstrated
- **Definitions** (`#Collector`) - Reusable, immutable base configurations
- **Unification** (`&`) - Deep merging of configurations
- **Defaults** (`*value | type`) - Sensible defaults with override capability
- **Optional fields** (`field?`) - Flexible configuration options
- **Disjunctions** (`"a" | "b"`) - Constrained choices
- **List operations** (`list.Concat`, indexing, slicing) - Dynamic list manipulation
- **Field references** (`base.#Collector.service.pipelines.traces.processors[0]`) - Direct access to nested fields
- **Validation** - Automatic schema validation and conflict detection
## Advanced Patterns
### Pipeline Processor Manipulation
The examples demonstrate several patterns for modifying the base pipeline processors:
```cue
// Reference base processors directly
processors: [
base.#Collector.service.pipelines.traces.processors[0], // "memory_limiter"
"custom_processor",
base.#Collector.service.pipelines.traces.processors[1] // "batch"
]
// Prepend processors
processors: list.Concat([["resource"], base.#Collector.service.pipelines.traces.processors])
// Append processors
processors: list.Concat([base.#Collector.service.pipelines.traces.processors, ["sampler"]])
// Complex insertions using slicing
processors: list.Concat([
[base.#Collector.service.pipelines.traces.processors[0]],
["transform"],
base.#Collector.service.pipelines.traces.processors[1:]
])
```