### Local Development Setup for OTelBin

Source: https://context7.com/dash0hq/otelbin/llms.txt

Provides instructions for setting up OTelBin locally, including cloning the repository, installing dependencies, configuring environment variables, and running development commands.

```bash
# Clone the repository
git clone https://github.com/dash0hq/otelbin.git
cd otelbin

# Install dependencies for the main application
cd packages/otelbin
npm install

# Copy environment variables template
cp .env.example .env.local

# Required environment variables in .env.local:
# NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
# CLERK_SECRET_KEY=sk_test_...
# UPSTASH_REDIS_REST_URL=https://...upstash.io
# UPSTASH_REDIS_REST_TOKEN=...
# COLLECTOR_CONFIGURATION_VALIDATION_URL=https://...
# COLLECTOR_CONFIGURATION_VALIDATION_API_KEY=...

# Start development server
npm run dev

# Run tests
npm run test

# Run linting
npm run lint

# Build for production
npm run build
```

--------------------------------

### CDK Deployment Output

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

Example output from the CDK deployment showing API endpoints.

```sh
otelbin-validation-backend-vali-95773.apikeyid = u8hnc02ug6
otelbin-validation-backend-vali-95773.apiname = otelbin-validation-backend-vali-95773
otelbin-validation-backend-vali-95773.apiurl = https://9tmz01s4ia.execute-api.us-east-2.amazonaws.com/prod/
otelbin-validation-backend-vali-95773.validationapiEndpointE3717CC6 = https://9tmz01s4ia.execute-api.us-east-2.amazonaws.com/prod/
```

--------------------------------

### Complete OpenTelemetry Collector Configuration Example

Source: https://context7.com/dash0hq/otelbin/llms.txt

A comprehensive example of an OpenTelemetry Collector configuration in YAML format, including receivers, processors, exporters, connectors, extensions, and service pipelines.

```yaml
# Complete OpenTelemetry Collector configuration example
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  prometheus:
    config:
      scrape_configs:
        - job_name: 'app-metrics'
          scrape_interval: 15s
          static_configs:
            - targets: ['localhost:8080']

processors:
  batch:
    timeout: 10s
    send_batch_size: 10000

  memory_limiter:
    check_interval: 1s
    limit_mib: 1000
    spike_limit_mib: 200

  attributes:
    actions:
      - key: environment
        value: production
        action: upsert

exporters:
  otlp:
    endpoint: otelcol:4317
    tls:
      insecure: true

  debug:
    verbosity: detailed

connectors:
  spanmetrics:
    histogram:
      explicit:
        buckets: [100us, 1ms, 10ms, 100ms, 1s]

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

service:
  extensions: [health_check, pprof, zpages]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp, debug]
    metrics:
      receivers: [otlp, prometheus, spanmetrics]
      processors: [memory_limiter, batch]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch, attributes]
      exporters: [otlp]
```

--------------------------------

### Get Preview Image for Short Link Configuration

Source: https://context7.com/dash0hq/otelbin/llms.txt

Retrieve a PNG preview image of a pipeline visualization for a given short link configuration. The image is 1200x630 pixels.

```bash
curl "https://www.otelbin.io/s/abc123def456.../img" -o preview.png
```

--------------------------------

### Configure AWS CLI Profile

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

Example configuration for an AWS CLI profile used for deployment.

```json
[otelbin-dev]
aws_access_key_id = <access_key_id>
aws_secret_access_key = <secret_access_key>
region = <region>
output = json
```

--------------------------------

### GET /s/{id}

Source: https://context7.com/dash0hq/otelbin/llms.txt

Retrieves the full configuration URL from a short link ID.

```APIDOC
## GET /s/{id}

### Description
Retrieves the full configuration URL from a short link ID, resulting in a redirect to the full OTelBin URL.

### Method
GET

### Endpoint
/s/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The short link identifier
```

--------------------------------

### Get Supported Distributions API

Source: https://context7.com/dash0hq/otelbin/llms.txt

Retrieves a list of all supported OpenTelemetry Collector distributions and their available versions.

```bash
curl "https://www.otelbin.io/validation/supported-distributions"
```

--------------------------------

### GET /validation/supported-distributions

Source: https://context7.com/dash0hq/otelbin/llms.txt

Retrieves a list of all supported OpenTelemetry Collector distributions and their available versions.

```APIDOC
## GET /validation/supported-distributions

### Description
Returns metadata for all supported OpenTelemetry Collector distributions, including provider information and available release versions.

### Method
GET

### Endpoint
/validation/supported-distributions

### Response
#### Success Response (200)
- **[distribution_id]** (object) - Metadata for each distribution including name, provider, description, and releases.
```

--------------------------------

### TypeScript Interfaces for Pipeline Configuration

Source: https://context7.com/dash0hq/otelbin/llms.txt

TypeScript interfaces for programmatically working with OpenTelemetry Collector pipeline configurations. Includes an example of parsing and iterating over pipeline data.

```typescript
// Pipeline configuration interfaces
interface IPipeline {
  exporters?: string[];
  processors?: string[];
  receivers?: string[];
}

interface IPipelines {
  [key: string]: IPipeline;
}

interface IService {
  pipelines?: IPipelines;
}

interface IConfig {
  [key: string]: unknown;
  connectors: object;
  service?: IService;
}

// Example usage: Parse and visualize a configuration
import JsYaml from 'js-yaml';

const yamlConfig = `
receivers:
  otlp:
    protocols:
      grpc:
processors:
  batch:
exporters:
  otlp:
    endpoint: collector:4317
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
`;

const config = JsYaml.load(yamlConfig, { schema: 'failsafe' }) as IConfig;
const pipelines = config?.service?.pipelines;

// Iterate over pipelines
if (pipelines) {
  for (const [pipelineName, pipeline] of Object.entries(pipelines)) {
    console.log(`Pipeline: ${pipelineName}`);
    console.log(`  Receivers: ${pipeline.receivers?.join(', ')}`);
    console.log(`  Processors: ${pipeline.processors?.join(', ')}`);
    console.log(`  Exporters: ${pipeline.exporters?.join(', ')}`);
  }
}
```

--------------------------------

### Run OTelBin Locally

Source: https://github.com/dash0hq/otelbin/blob/main/CONTRIBUTING.md

Use these commands to set up and run the OTelBin application locally after cloning the repository and configuring environment variables.

```bash
cd packages/otelbin
npm i
npm run dev
```

--------------------------------

### Add Release Information for a New Distribution

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

After adding initial metadata, populate the `releases` array with specific release details for testing. Include the version tag, artifact name, and release timestamp.

```json
{
   ...,
   "my-distro": {
      "provider": "My company",
      "description": "Much wow",
      "website": "https://my-company.io",
      "icon": "my-icon",
      "repository": "<github_org>/<repo_name>",
      "releases": [
         {
            "version": "v0.88.0", # Tag name to be shown in OTelBin, keep it SemVer please
            "artifact": "otelcol_0.88.0_linux_amd64.rpm", # Name of the artifact attached to the release; could also be a full URL to download the package
            "released_at": "2023-10-24T11:24:58.000Z"
         }
   }
}
```

--------------------------------

### POST /s/new

Source: https://context7.com/dash0hq/otelbin/llms.txt

Creates a shareable short URL for an OpenTelemetry Collector configuration.

```APIDOC
## POST /s/new

### Description
Creates a shareable short URL for an OpenTelemetry Collector configuration. Requires authentication.

### Method
POST

### Endpoint
/s/new

### Response
#### Success Response (200)
- **shortLink** (string) - The generated short URL
- **imgURL** (string) - The URL for the configuration image preview
```

--------------------------------

### Add New Distribution Metadata to JSON

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

When adding a new distribution, include its metadata in the `supported-distributions.json` file. This includes provider, description, icon, website, repository, and an empty releases array.

```json
{
   ...,
   "my-distro": {
      "provider": "My company",
      "description": "Much wow",
      "icon": "my-icon",
      "website": "https://my-company.io",
      "repository": "<github_org>/<repo_name>",
      "releases": []
   }
}
```

--------------------------------

### Create Short Link API

Source: https://context7.com/dash0hq/otelbin/llms.txt

Generates a shareable short URL for a given configuration. Requires authentication.

```bash
curl -X POST "https://www.otelbin.io/s/new" \
  -H "Content-Type: text/plain" \
  -d "https://www.otelbin.io/?#config=*receivers:~otlp:~*~*protocols:~*~*~*grpc:~*~*~*http:*processors:~batch:*exporters:~otlp:~*~*endpoint:~otelcol:4317*service:~pipelines:~*~*traces:~*~*~*receivers:~!otlp!~*~*~*processors:~!batch!~*~*~*exporters:~!otlp!"
```

--------------------------------

### Retrieve Supported Distributions

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

Curl command to fetch supported distribution versions from the Validation API.

```sh
# Retrieving the supported distribution versions
$ curl https://${API_ID}.execute-api.${AWS_REGION}.amazonaws.com/prod/validation/supported-distributions --header "X-Api-Key: ${API_KEY}"

{
  "otelcol-core": {
    "provider": "OpenTelemetry Community - Core",
    "description": "OpenTelemetry Collector core community builds",
    "website": "https://opentelemetry.io",
    "repository": "open-telemetry/opentelemetry-collector-releases",
    "releases": [
      {
        "version": "v0.87.0",
        "artifact": "otelcol_0.87.0_linux_amd64.rpm",
        "released_at": "2023-10-11T06:06:02.000Z"
      },
      ...
   ]
  },
  ...
}
```

--------------------------------

### Deploy with AWS CDK

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

Command to trigger the deployment process using the specified AWS profile.

```sh
GH_TOKEN=<token> npm run deploy --profile otelbin-dev
```

--------------------------------

### Serialize Configuration to URL State

Source: https://context7.com/dash0hq/otelbin/llms.txt

Serializes configuration state into URL hash parameters for shareable links. Ensure the editorBinding is correctly defined with its prefix, name, and fallback configuration.

```typescript
import { serializeUrlState } from '~/lib/urlState/serializeUrlState';
import { editorBinding } from '~/components/monaco-editor/editorBinding';

// Editor binding defines how configuration is stored in URL
const editorBinding = {
  prefix: '',
  name: 'config',
  fallback: `
receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  otlp:
    endpoint: otelcol:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
`.trim()
} as const;

// Serialize configuration to URL
const pathName = serializeUrlState(
  [editorBinding],
  '/',
  new URLSearchParams(),
  new URLSearchParams(),
  {
    config: yamlConfig
  }
);

// Result: /?#config=*receivers:~otlp:~*~*protocols:...
```

--------------------------------

### Embed Collector Configuration Badge

Source: https://context7.com/dash0hq/otelbin/llms.txt

Embed a shields.io-powered badge in your documentation that links to your OTelBin configuration. Markdown and HTML versions are provided.

```markdown
<!-- Embed a badge that links to your OTelBin configuration -->
[![OpenTelemetry collector configuration on OTelBin](https://www.otelbin.io/badges/collector-config)](https://www.otelbin.io/s/your-short-link)
```

```html
<a href="https://www.otelbin.io/s/your-short-link">
  <img src="https://www.otelbin.io/badges/collector-config" alt="OpenTelemetry collector configuration on OTelBin">
</a>
```

--------------------------------

### Validate Configuration

Source: https://github.com/dash0hq/otelbin/blob/main/packages/otelbin-validation/README.md

Curl command to validate a configuration against the API.

```sh
# Validating a an empty configuration
$ curl https://${API_ID}.execute-api.${AWS_REGION}.amazonaws.com/prod/validation/${DISTRO_NAME}/${VERSION} --header "X-Api-Key: ${API_KEY}" --data "${CONFIGURATION}"
{"message":"The provided configuration is invalid","error":"the provided configuration is empty"}
```

--------------------------------

### Resolve Short Link API

Source: https://context7.com/dash0hq/otelbin/llms.txt

Retrieves the full configuration URL from a short link ID, resulting in an HTTP 302 redirect.

```bash
curl -L "https://www.otelbin.io/s/abc123def456..."
```

--------------------------------

### Create Deep Link from YAML Configuration

Source: https://context7.com/dash0hq/otelbin/llms.txt

Use this curl command to create a deep link for an OpenTelemetry Collector configuration by sending the YAML content as plain text.

```bash
curl -X POST "https://www.otelbin.io/deep-link" \
  -H "Content-Type: text/plain" \
  -d 'receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]'
```

--------------------------------

### AWS CDK Stack for Validation Backend Deployment

Source: https://context7.com/dash0hq/otelbin/llms.txt

Deploys the validation backend using AWS CDK v2, creating Lambda functions for each supported OpenTelemetry distribution and version. Each Lambda function uses a Docker image containing the collector binary.

```typescript
// AWS CDK stack for validation backend deployment
import { App, Stack, StackProps, Duration } from 'aws-cdk-lib';
import { RestApi, LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';
import { DockerImageFunction, DockerImageCode } from 'aws-cdk-lib/aws-lambda';

interface Distribution {
  provider: string;
  description: string;
  website: string;
  repository: string;
  releases: Release[];
}

interface Release {
  version: string;
  artifact: string;
}

// Deploy validation stack
const app = new App();

new OTelBinValidationStack(app, 'otelbin-validation-prod', {
  testEnvironmentName: 'prod',
  githubToken: process.env.GH_TOKEN!,
  dash0AuthorizationToken: process.env.DASH0_AUTHORIZATION_TOKEN
});

// Each distribution/version gets its own Lambda function
// Lambda uses Docker image with actual collector binary installed
// Example: validation/otelcol-contrib/v0.148.0 -> dedicated Lambda
```

--------------------------------

### POST /validation

Source: https://context7.com/dash0hq/otelbin/llms.txt

Validates an OpenTelemetry Collector configuration against a specific distribution and version.

```APIDOC
## POST /validation

### Description
Validates an OpenTelemetry Collector configuration against a specific distribution and version by running the actual collector binary.

### Method
POST

### Endpoint
/validation

### Parameters
#### Query Parameters
- **distro** (string) - Required - The distribution name (e.g., otelcol-contrib)
- **version** (string) - Required - The version tag (e.g., v0.148.0)

#### Request Body
- **config** (string) - Required - The YAML configuration string
- **env** (object) - Optional - Environment variables for the collector

### Request Example
{
  "config": "receivers:\n  otlp:\n    protocols:\n      grpc:\n      http:\n\nprocessors:\n  batch:\n\nexporters:\n  otlp:\n    endpoint: otelcol:4317\n\nservice:\n  pipelines:\n    traces:\n      receivers: [otlp]\n      processors: [batch]\n      exporters: [otlp]",
  "env": {
    "OTEL_ENDPOINT": "https://collector.example.com"
  }
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
{
  "message": "Configuration is valid"
}
```

--------------------------------

### Lambda Handler for Configuration Validation

Source: https://context7.com/dash0hq/otelbin/llms.txt

Handles configuration validation requests by writing the configuration to a temporary file and executing the OpenTelemetry Collector's validate command. It can extract error paths from validation failures.

```typescript
// Lambda handler for configuration validation
import type { APIGatewayEvent, APIGatewayProxyResult } from 'aws-lambda';

interface ValidationPayload {
  config: string;
  env: { [key: string]: string };
}

exports.handler = async (event: APIGatewayEvent): Promise<APIGatewayProxyResult> => {
  const body = JSON.parse(event.body!) as ValidationPayload;
  const { config, env } = body;

  // Write config to temp file
  await writeFile('/tmp/config.yaml', config);

  // Run collector validate command
  // For standard collectors:
  await spawnAsync('/bin/sh', [
    '-c',
    '/usr/bin/otelcol validate --config=/tmp/config.yaml'
  ], {
    env: { ...process.env, ...env },
    timeout: 10_000
  });

  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Configuration is valid' })
  };
};

// Extract error paths from validation failures
function extractErrorPath(errorMessage: string): string[] {
  return errorMessage.match(/^((?:[\w/]+(?:::)?)+):[^:]/)?.[1].split('::') || [];
}

// Example error path extraction:
// "service::pipelines::traces::receivers: receiver \"foo\" is not configured"
// Returns: ["service", "pipelines", "traces", "receivers"]
```

--------------------------------

### Validate Configuration API

Source: https://context7.com/dash0hq/otelbin/llms.txt

Validates a YAML configuration against a specific OpenTelemetry Collector distribution version.

```bash
curl -X POST "https://www.otelbin.io/validation?distro=otelcol-contrib&version=v0.148.0" \
  -H "Content-Type: application/json" \
  -d '{
    "config": "receivers:\n  otlp:\n    protocols:\n      grpc:\n      http:\n\nprocessors:\n  batch:\n\nexporters:\n  otlp:\n    endpoint: otelcol:4317\n\nservice:\n  pipelines:\n    traces:\n      receivers: [otlp]\n      processors: [batch]\n      exporters: [otlp]",
    "env": {
      "OTEL_ENDPOINT": "https://collector.example.com"
    }
  }'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.