Tulip OpenTelemetry Distribution Assistant

This skill provides expert guidance for working with Tulip, OllyGarden's commercially supported distribution of the OpenTelemetry Collector.

What This Skill Does

Assists developers working on Tulip by providing:

Project Context

**Tulip** is a commercial, enterprise-supported OpenTelemetry Collector distribution built using the OpenTelemetry Collector Builder (ocb). It follows upstream OpenTelemetry architecture with custom branding and enterprise features.

**Key Facts:**

Instructions for AI Agent

1. Understanding the Build Architecture

When asked about the build system or how Tulip works:

1. Explain the **manifest-driven architecture**:

- `distributions/tulip/manifest.yaml` defines all components and versions

- OpenTelemetry Collector Builder (ocb) reads manifest and generates Go source

- Generated files in `distributions/tulip/_build/` should NEVER be manually edited

- Build flow: `manifest.yaml → ocb → _build/*.go → go build → binary`

2. Explain ocb auto-installation:

- The Makefile automatically installs ocb to `~/bin/ocb` if not found

- No manual installation required for basic development

2. Adding or Updating Components

When asked to add or update OpenTelemetry components:

**Steps to add a component:**

1. Edit `distributions/tulip/manifest.yaml`

2. Add component under appropriate section (extensions/receivers/exporters/processors/connectors)

3. Include gomod path and version

4. Run `make generate-sources` to regenerate build files

5. Run `go mod tidy` to update dependencies

6. Run `make build` to compile

7. Run `make test` to verify

**Steps to update versions:**

1. Edit version numbers in `distributions/tulip/manifest.yaml`

2. Ensure version compatibility across all components (contrib at v0.X.0, core at v0.X.0)

3. Run `make generate` (regenerates sources + goreleaser config)

4. Run `go mod tidy`

5. Run `make test`

**Critical:** All OpenTelemetry components must use compatible versions. They version together.

3. Build Commands Reference

Provide these commands based on context:

**Full build (generate + compile):**

```bash

make build

```

**Generate source code only:**

```bash

make generate-sources

Or:

./scripts/build.sh -d tulip -s true -b ocb

```

**Run tests:**

```bash

make test

```

**Full CI workflow:**

```bash

make ci # Runs: check, build, test, goreleaser validation

```

**Format code (required after changes):**

```bash

go fmt ./...

```

**Generate goreleaser config:**

```bash

make generate-goreleaser

```

4. Testing Guidance

When asked about testing:

1. Explain test architecture:

- Test scripts in `test/` directory

- Distribution-agnostic using `${distribution}` variable

- Test flow: build → start collector → generate traces → verify → cleanup

2. Provide test commands:

```bash

# Test single distribution

test/test.sh -d tulip

# Test all distributions

test/test-all.sh

```

3. Note that test scripts use:

- `_build/${distribution}` for binary path

- `${distribution}-test.yaml` for config

- `test/start-otelcol.sh` for collector startup

5. Directory Structure Explanation

When asked about project structure, explain:

```

distributions/tulip/

├── manifest.yaml # Component manifest (SINGLE SOURCE OF TRUTH)

├── config.yaml # Default runtime configuration

├── Dockerfile # Container image definition

├── tulip.service # systemd service file

├── tulip.conf # systemd environment variables

├── tulip-test.yaml # Test configuration

├── preinstall.sh # Creates tulip user/group

├── postinstall.sh # Enables systemd service

├── preremove.sh # Stops service before removal

├── .goreleaser.yaml # GENERATED (do not edit manually)

└── _build/ # GENERATED by ocb (not committed)

├── components.go # Component registration

├── main.go # Entry point

├── main_others.go # Unix-specific entry

├── go.mod # Generated module file

└── tulip # Compiled binary

```

6. Branding and Naming Conventions

Always use correct Tulip branding:

7. Development Workflow

When asked about the development process, provide this workflow:

1. Make changes to `manifest.yaml` or config files

2. Run `make generate` (regenerates sources + goreleaser config)

3. Run `go mod tidy` (update dependencies)

4. Run `go fmt ./...` (format code)

5. Run `make test` (verify tests pass)

6. Stage changes for review (do not commit directly)

8. Release and Packaging

When asked about releases or packaging:

**Tools required:**

```bash

# Using Homebrew

brew install goreleaser

# Or download from https://github.com/goreleaser/goreleaser/releases

```

**Verify installation:**

```bash

ocb version # or ~/bin/ocb

goreleaser --version

```

9. Critical Rules

Always emphasize these rules:

10. Troubleshooting Common Issues

When users encounter problems:

**Component version conflicts:**

**Build failures:**

**Test failures:**

Examples

**Example 1: Adding a new receiver**

```yaml

User asks: "Add the prometheusreceiver to Tulip"

Response:

I'll help you add the Prometheus receiver to Tulip.

Steps:

1. Edit distributions/tulip/manifest.yaml

2. Add to the receivers section:

- gomod: go.opentelemetry.io/collector/receiver/prometheusreceiver v0.X.0

3. Run make generate-sources

4. Run go mod tidy

5. Run make test

```

**Example 2: Updating component versions**

```yaml

User asks: "Update all components to v0.95.0"

Response:

I'll guide you through updating to v0.95.0.

Critical: All components must be updated together for version compatibility.

Steps:

1. Edit distributions/tulip/manifest.yaml

2. Update version to v0.95.0 for:

- All contrib components (receivers, processors, exporters, connectors)

- All core components (extensions)

3. Run make generate (regenerates sources and goreleaser config)

4. Run go mod tidy

5. Run make test to verify compatibility

```

Notes