### Quick Start Effect Server

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/sdks/effect-server.md

This example demonstrates how to initialize the Maple SDK with a service name and run a simple Effect program that logs a message and is traced.

```typescript
import { Maple } from "@maple-dev/effect-sdk"
import { Effect } from "effect"

const TracerLive = Maple.layer({
	sserviceName: "my-effect-app",
})

const program = Effect.gen(function* () {
	yield* Effect.log("Hello from Effect!")
}).pipe(Effect.withSpan("hello-maple"))

Effect.runPromise(program.pipe(Effect.provide(TracerLive)))
```

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

### Install @maple/otel-helpers

Source: https://github.com/makisuo/maple/blob/main/packages/otel-helpers/README.md

Install the package and its peer dependency `@opentelemetry/api`.

```bash
npm install @maple/otel-helpers @opentelemetry/api
```

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

### Database Node Creation Example

Source: https://github.com/makisuo/maple/blob/main/docs/attributes.md

Shows how to create a database node in the service map by pairing `db.system` with `peer.service` on a `Client` span. This example illustrates a call to a PostgreSQL database.

```text
SELECT * FROM users  (span.kind=Client, db.system=postgresql, peer.service=postgresql)
                            └──> draws an edge api → postgresql DB node
```

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

### Install Specific Instrumentation Packages

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-python.md

Install individual instrumentation packages for libraries like Flask, Requests, and SQLAlchemy for more granular control.

```bash
pip install opentelemetry-instrumentation-flask \
  opentelemetry-instrumentation-requests \
  opentelemetry-instrumentation-sqlalchemy
```

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

### Install OpenTelemetry Go Dependencies

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-go.md

Install the necessary OpenTelemetry SDK and exporter packages for Go.

```bash
go get go.opentelemetry.io/otel \
go.opentelemetry.io/otel/sdk \
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp
```

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

### Install Dependencies with Bun

Source: https://github.com/makisuo/maple/blob/main/README.md

Installs all project dependencies using Bun. Ensure Bun version is >= 1.3.

```bash
bun install
```

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

### Install @maple-dev/effect-sdk for Effect 4+

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/sdks/effect.md

Install the SDK and Effect for version 4 and above.

```bash
npm install @maple-dev/effect-sdk effect
```

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

### Install OTel HTTP Log Exporter

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-python.md

Install the necessary package to enable OTel log export over HTTP.

```bash
pip install opentelemetry-exporter-otlp-proto-http
```

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

### Install OpenTelemetry Dependencies

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-python.md

Install the necessary OpenTelemetry SDK, OTLP HTTP exporter, and core instrumentation packages using pip.

```bash
pip install opentelemetry-sdk \
  opentelemetry-exporter-otlp-proto-http \
  opentelemetry-instrumentation
```

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

### Install FastAPI Instrumentation

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-python.md

Install the dedicated instrumentation package for FastAPI to automatically trace all routes.

```bash
pip install opentelemetry-instrumentation-fastapi
```

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

### Install OpenTelemetry Go SDK and HTTP Exporters

Source: https://github.com/makisuo/maple/blob/main/skills/maple-go-style/SKILL.md

Install the necessary OpenTelemetry packages for Go, including the SDK and HTTP exporters for trace, log, and metric data.

```bash
go get \
  go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
  go.opentelemetry.io/otel/exporters/otlp/otlplogs/otlploghttp \
  go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp \
  go.opentelemetry.io/otel/log \
  go.opentelemetry.io/otel/sdk/log
```

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

### Install Portless CA Certificate

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Run this command once per machine for first-time setup to install portless's local CA certificate into your system's trust store.

```bash
npx portless trust
```

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

### Install Ktor Server Tracing

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-kotlin.md

Install the `KtorServerTracing` feature in your Ktor application's `configureMonitoring` function and set the OpenTelemetry instance.

```kotlin
import io.ktor.server.application.*
import io.opentelemetry.instrumentation.ktor.v3_0.server.KtorServerTracing

fun Application.configureMonitoring() {
    install(KtorServerTracing) {
        setOpenTelemetry(Telemetry.init())
    }
}
```

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

### Install Ktor Client Tracing

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-kotlin.md

Configure the `KtorClientTracing` feature for your `HttpClient` and set the OpenTelemetry instance.

```kotlin
val client = HttpClient(CIO) {
    install(KtorClientTracing) {
        setOpenTelemetry(GlobalOpenTelemetry.get())
    }
}
```

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

### Instrument Go gRPC Server and Client

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-go.md

Install the otelgrpc package and use otelgrpc.NewServerHandler and otelgrpc.NewClientHandler to instrument gRPC servers and clients.

```bash
go get go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc
```

```go
import "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"

// Server
server := grpc.NewServer(
	grpc.StatsHandler(otelgrpc.NewServerHandler()),
)

// Client
conn, err := grpc.Dial(addr,
	grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
)
```

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

### Create Astro Project with Minimal Template

Source: https://github.com/makisuo/maple/blob/main/apps/landing/README.md

Use this command to create a new Astro project using the minimal template. Ensure you have Bun installed.

```sh
bun create astro@latest -- --template minimal
```

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

### Install Maple-OTel Helm Chart

Source: https://github.com/makisuo/maple/blob/main/deploy/maple-otel/README.md

Install the maple-otel Helm chart with basic configuration. Ensure you replace placeholder values with your actual ClickHouse endpoint and password.

```bash
helm install maple-otel oci://ghcr.io/makisuo/charts/maple-otel \
  --version 0.1.0 \
  --namespace maple --create-namespace \
  --set maple.orgId=org_xxx \
  --set maple.clickhouse.endpoint=https://your-ch.example.com \
  --set maple.clickhouse.password.value=$CH_PASSWORD
```

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

### Example Throughput Calculation

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/concepts/sampling-throughput.md

An example demonstrating the throughput calculation with 10% sampling, 500 sampled root spans, and a 60-second duration.

```plaintext
estimatedTotal = 500 * 10 = 5000
throughput     = 5000 / 60 = ~83 req/s
```

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

### Install @maple-dev/effect-sdk for Effect 3

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/sdks/effect.md

Install the SDK and necessary Effect packages for version 3. Note that duration config types differ.

```bash
npm install @maple-dev/effect-sdk@effect-v3 effect @effect/platform @effect/opentelemetry
```

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

### Start Maple API and Web Development Servers

Source: https://github.com/makisuo/maple/blob/main/README.md

Launch the Maple API and web development servers using Bun filters. Ensure environment variables for authentication and database are correctly set.

```bash
bun --filter=@maple/api dev
bun --filter=@maple/web dev
```

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

### Install Node.js OpenTelemetry Dependencies

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-nodejs.md

Install the necessary OpenTelemetry packages for Node.js instrumentation.

```bash
npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/exporter-logs-otlp-http
```

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

### Run maple-onboard Command

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/getting-started/introduction.md

Use this command to automatically onboard all services in a repository, install OpenTelemetry, and configure traces, logs, and metrics.

```bash
maple-onboard
```

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

### Instrument Go Database with otelsql

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-go.md

Install the otelsql package and use otelsql.Open to instrument database connections.

```bash
go get github.com/XSAM/otelsql
```

```go
import "github.com/XSAM/otelsql"

db, err := otelsql.Open("postgres", dsn)
```

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

### Install OpenTelemetry Packages

Source: https://github.com/makisuo/maple/blob/main/skills/maple-csharp-style/SKILL.md

Add the necessary OpenTelemetry packages to your .NET project using the dotnet CLI.

```bash
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http
```

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

### Install Dependencies for Next.js Instrumentation

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-nextjs.md

Install the necessary OpenTelemetry packages for Next.js tracing and logging. `@vercel/otel` bundles trace exporters, while separate packages are needed for log records.

```bash
npm install @vercel/otel \
  @opentelemetry/api \
  @opentelemetry/sdk-logs \
  @opentelemetry/exporter-logs-otlp-http
```

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

### Install Maple-OTel Helm Chart with Existing Secret

Source: https://github.com/makisuo/maple/blob/main/deploy/maple-otel/README.md

A more secret-hygienic installation of the maple-otel Helm chart using an existing Kubernetes secret for the ClickHouse password.

```bash
kubectl -n maple create secret generic maple-clickhouse-password \
  --from-literal=password=$CH_PASSWORD

helm install maple-otel oci://ghcr.io/makisuo/charts/maple-otel \
  --version 0.1.0 \
  --namespace maple \
  --set maple.orgId=org_xxx \
  --set maple.clickhouse.endpoint=https://your-ch.example.com \
  --set maple.clickhouse.password.existingSecret.name=maple-clickhouse-password \
  --set maple.clickhouse.password.existingSecret.key=password
```

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

### Instrument Go HTTP Server with otelhttp

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-go.md

Install the otelhttp instrumentation package and wrap your HTTP handler to trace incoming requests.

```bash
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
```

```go
import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"

mux := http.NewServeMux()
mux.HandleFunc("/api/orders", handleOrders)

// Wrap the entire handler
handler := otelhttp.NewHandler(mux, "server")
http.ListenAndServe(":8080", handler)
```

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

### Service Map Edge Creation Example

Source: https://github.com/makisuo/maple/blob/main/docs/attributes.md

Demonstrates how to emit `peer.service` on a `Client` span to draw a service-to-service edge in the service map. This example shows an API service making a client call to a users-service.

```text
GET /v1/users  (service.name=api, span.kind=Client, peer.service=users-service)
                            └──> draws an edge api → users-service
```

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

### Bootstrap Auto-Instrumentation

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-python.md

Use the opentelemetry-bootstrap command to install instrumentations for your packages and then run your application with the opentelemetry-instrument wrapper.

```bash
opentelemetry-bootstrap -a install
```

```bash
opentelemetry-instrument python app.py
```

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

### Maple Ingest Configuration Example

Source: https://github.com/makisuo/maple/blob/main/skills/maple-onboarding-style/SKILL.md

Inline the Maple endpoint and project ingest key directly in the bootstrap source. Use the `MAPLE_TEST` sentinel during pairing.

```text
MAPLE_ENDPOINT = "https://ingest.maple.dev"
MAPLE_KEY      = "maple_…"        # or "MAPLE_TEST" while pairing
```

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

### Install Maple Collector from Local Repository

Source: https://github.com/makisuo/maple/blob/main/deploy/k8s-infra/README.md

Install the collector using Helm from the local repository path. This is useful for development or testing. Ensure you replace YOUR_MAPLE_INGEST_KEY and set global.clusterName.

```bash
helm upgrade --install maple-k8s-infra ./deploy/k8s-infra \
  --namespace maple \
  --create-namespace \
  --set maple.ingestKey.value=YOUR_MAPLE_INGEST_KEY \
  --set global.clusterName=production
```

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

### Install Maple Kubernetes Infrastructure Helm Chart

Source: https://github.com/makisuo/maple/blob/main/docs/service-map-infrastructure.md

Install the Helm chart to enable infrastructure data collection. Replace YOUR_MAPLE_INGEST_KEY with your actual key and adjust global.clusterName as needed. For self-hosted Maple, append the ingest endpoint.

```bash
helm upgrade --install maple-k8s-infra \
  oci://ghcr.io/makisuo/charts/maple-k8s-infra \
  --namespace maple --create-namespace \
  --set maple.ingestKey.value=YOUR_MAPLE_INGEST_KEY \
  --set global.clusterName=production

kubectl annotate namespace shop \
  instrumentation.opentelemetry.io/inject-sdk=maple/maple-default

kubectl rollout restart deployment -n shop
```

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

### Tinybird Local Development Mode

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Start Tinybird in local development mode using this command.

```bash
bun tinybird:dev
```

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

### Run Local Docker Stack

Source: https://github.com/makisuo/maple/blob/main/README.md

Starts the local multi-service Docker environment, including the API, web frontend, ingest gateway, and OTEL collector. Use '--build' to ensure images are up-to-date.

```bash
docker compose -f docker-compose.yml up --build
```

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

### Initialize Node.js SDK with OTLP Exporters

Source: https://github.com/makisuo/maple/blob/main/skills/maple-nodejs-style/SKILL.md

Configure the NodeSDK with resource attributes and OTLP exporters for traces, logs, and metrics. Ensure the SDK starts before application code by using the --import flag.

```typescript
import {
	NodeSDK
} from "@opentelemetry/sdk-node"
import {
	getNodeAutoInstrumentations
} from "@opentelemetry/auto-instrumentations-node"
import {
	OTLPTraceExporter
} from "@opentelemetry/exporter-trace-otlp-http"
import {
	OTLPLogExporter
} from "@opentelemetry/exporter-logs-otlp-http"
import {
	OTLPMetricExporter
} from "@opentelemetry/exporter-metrics-otlp-http"
import {
	BatchLogRecordProcessor
} from "@opentelemetry/sdk-logs"
import {
	PeriodicExportingMetricReader
} from "@opentelemetry/sdk-metrics"
import {
	resourceFromAttributes
} from "@opentelemetry/resources"

const MAPLE_ENDPOINT = "https://ingest.maple.dev"
const MAPLE_KEY = "MAPLE_TEST" // set by maple-onboard skill on pairing

const headers = { authorization: `Bearer ${MAPLE_KEY}` }

const sdk = new NodeSDK({
	resource: resourceFromAttributes({
		"service.name": "my-node-app",
		"deployment.environment.name": process.env.NODE_ENV ?? "development",
		"vcs.repository.url.full": "https://github.com/acme/my-node-app",
		"vcs.ref.head.revision":
			process.env.RAILWAY_GIT_COMMIT_SHA ??
			process.env.GITHUB_SHA ??
			process.env.GIT_COMMIT,
	}),
	traceExporter: new OTLPTraceExporter({
		url: `${MAPLE_ENDPOINT}/v1/traces`,
		headers,
	}),
	logRecordProcessors: [
		new BatchLogRecordProcessor(
			new OTLPLogExporter({ url: `${MAPLE_ENDPOINT}/v1/logs`, headers }),
		),
	],
	metricReader: new PeriodicExportingMetricReader({
		exporter: new OTLPMetricExporter({
			url: `${MAPLE_ENDPOINT}/v1/metrics`,
			headers,
		}),
	}),
	instrumentations: [getNodeAutoInstrumentations()]
})

sdk.start()
```

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

### Run Individual App Dev Tasks

Source: https://github.com/makisuo/maple/blob/main/README.md

Starts the development server for a specific application within the monorepo using workspace filters. Replace '@maple/web' with the desired app package name.

```bash
bun --filter=@maple/web dev
```

```bash
bun --filter=@maple/api dev
```

```bash
bun --filter=@maple/ingest dev
```

```bash
bun --filter=@maple/landing dev
```

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

### Throughput Calculation Example

Source: https://github.com/makisuo/maple/blob/main/docs/sampling-throughput.md

Illustrates how to calculate estimated total requests and throughput per second using the calculated sample rate. This method correctly handles mixed sampling rates.

```plaintext
estimatedTotal = sum(SampleRate)        -- per-row weighted sum
throughput     = estimatedTotal / durationSeconds
```

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

### Creating Bounded Business Spans in Kotlin

Source: https://github.com/makisuo/maple/blob/main/skills/maple-kotlin-style/SKILL.md

Define custom spans for specific business operations within your Kotlin code. This example demonstrates how to start, manage, and end a span, including error recording and status setting.

```kotlin
private val tracer = GlobalOpenTelemetry.getTracer("orders.api")

suspend fun submitOrder(orderId: String, tenantId: String) {
    val span = tracer.spanBuilder("order.submit")
        .setAttribute("tenant.id", tenantId)
        .setAttribute("order.id", orderId)
        .startSpan()
    try {
        span.makeCurrent().use {
            chargeOrder(orderId)
        }
    } catch (e: Exception) {
        span.recordException(e)
        span.setStatus(StatusCode.ERROR, e.message ?: "")
        throw e
    } finally {
        span.end()
    }
}
```

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

### Preview Production Build with Bun

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Run this command to preview the production build of the project locally.

```bash
bun preview
```

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

### Open Drizzle Studio

Source: https://github.com/makisuo/maple/blob/main/docs/persistence.md

Launch Drizzle Studio for database inspection and management.

```bash
bun run db:studio
```

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

### Build for Production with Bun

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Use this command to build the project for production deployment.

```bash
bun build
```

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

### Build Tinybird Project

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Use this command to build the Tinybird project.

```bash
bun tinybird:build
```

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

### Run Database Migrations

Source: https://github.com/makisuo/maple/blob/main/README.md

Execute database migration, generation, push, and studio commands using Bun filters. Migrations are applied automatically on API startup.

```bash
bun --filter=@maple/api db:migrate
bun --filter=@maple/db db:generate
bun --filter=@maple/db db:push
bun --filter=@maple/db db:studio
```

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

### Install Maple Collector with Existing Secret

Source: https://github.com/makisuo/maple/blob/main/deploy/k8s-infra/README.md

For production environments, create a Kubernetes secret for the ingest key and then install the collector using Helm. This avoids hardcoding the key in commands.

```bash
kubectl create secret generic maple-ingest-key \
  --namespace maple \
  --from-literal=ingest-key=YOUR_MAPLE_INGEST_KEY
```

```bash
helm upgrade --install maple-k8s-infra ./deploy/k8s-infra \
  --namespace maple \
  --set maple.ingestKey.existingSecret.name=maple-ingest-key \
  --set maple.ingestKey.existingSecret.key=ingest-key \
  --set global.clusterName=production
```

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

### Install Maple Collector with Bash Script

Source: https://github.com/makisuo/maple/blob/main/deploy/k8s-infra/README.md

Use this command to install the collector via a curl script. Ensure you replace YOUR_MAPLE_INGEST_KEY and set MAPLE_CLUSTER_NAME. The script requires confirmation unless MAPLE_INSTALL_YES=1 is set.

```bash
curl -fsSL https://raw.githubusercontent.com/Makisuo/maple/main/deploy/k8s-infra/install.sh | \
  MAPLE_INGEST_KEY=YOUR_MAPLE_INGEST_KEY \
  MAPLE_CLUSTER_NAME=production \
  bash
```

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

### Install Maple Collector with Helm OCI

Source: https://github.com/makisuo/maple/blob/main/deploy/k8s-infra/README.md

Install the collector directly from the OCI chart hosted on GHCR. This command sets the ingest key and cluster name. Use --namespace and --create-namespace for proper deployment.

```bash
helm upgrade --install maple-k8s-infra \
  oci://ghcr.io/makisuo/charts/maple-k8s-infra \
  --namespace maple \
  --create-namespace \
  --set-string maple.ingestKey.value=YOUR_MAPLE_INGEST_KEY \
  --set-string global.clusterName=production
```

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

### Run Node.js Application with Tracing

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-nodejs.md

Execute your Node.js application with the tracing configuration file loaded first using the `--import` flag.

```bash
node --import ./tracing.ts app.ts
```

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

### Run Dedicated Alerting Dev Task

Source: https://github.com/makisuo/maple/blob/main/README.md

Starts the development task specifically for the alerting service.

```bash
bun run dev:alerting
```

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

### Configure OpenTelemetry Tracer Provider in Go

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-go.md

Set up the tracer provider in your Go application's startup. This includes configuring the HTTP exporter, resource attributes, and batching.

```go
package main

import (
	"context"
	"log"
	"os"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	"go.opentelemetry.io/otel/sdk/resource"
	"go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

func initTracer(ctx context.Context) (*trace.TracerProvider, error) {
	exporter, err := otlptracehttp.New(ctx,
		otlptracehttp.WithEndpointURL("https://ingest.maple.dev/v1/traces"),
		otlptracehttp.WithHeaders(map[string]string{
			"Authorization": "Bearer YOUR_API_KEY",
		}),
	)
	if err != nil {
		return nil, err
	}

	res, err := resource.New(ctx,
		resource.WithAttributes(
			semconv.ServiceName("my-go-app"),
			semconv.DeploymentEnvironment(os.Getenv("DEPLOYMENT_ENV")),
		),
		resource.WithAttributes(
			semconv.ServiceVersion("1.0.0"),
		),
	)
	if err != nil {
		return nil, err
	}

	tp := trace.NewTracerProvider(
		trace.WithBatcher(exporter),
		trace.WithResource(res),
	)
	otel.SetTracerProvider(tp)
	return tp, nil
}

func main() {
	ctx := context.Background()

	tp, err := initTracer(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer tp.Shutdown(ctx)

	// Your application code here
}
```

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

### Install OpenTelemetry Dependencies for Rust

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-rust.md

Add these dependencies to your `Cargo.toml` to enable OpenTelemetry instrumentation in your Rust application.

```toml
[dependencies]
opentelemetry = "0.27"
opentelemetry_sdk = { version = "0.27", features = ["rt-tokio"] }
opentelemetry-otlp = { version = "0.27", features = ["http-proto", "reqwest-client"] }
opentelemetry-semantic-conventions = "0.27"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
tracing-opentelemetry = "0.28"
tokio = { version = "1", features = ["full"] }
```

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

### Deploy Tinybird to Cloud

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Execute this command to deploy the Tinybird project to Tinybird Cloud.

```bash
bun tinybird:deploy
```

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

### Remove Namespace Annotation

Source: https://github.com/makisuo/maple/blob/main/docs/service-map-infrastructure.md

To opt out of auto-instrumentation for a namespace, remove the specific annotation. This will cause new pods to start without auto-instrumentation.

```bash
kubectl annotate namespace <your-ns> instrumentation.opentelemetry.io/inject-sdk-
kubectl rollout restart deployment -n <your-ns>
```

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

### Initialize Telemetry at Startup

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-java.md

Call the Telemetry.init() method during application startup to initialize OpenTelemetry.

```java
public static void main(String[] args) {
    Telemetry.init();
    // your application
}
```

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

### Call Tracer Initialization in Rust Main

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-rust.md

Ensure the tracer is initialized by calling `init_tracing()` at the start of your `main` function and shut it down gracefully before exiting.

```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = telemetry::init_tracing()?;

    // Your application code here

    provider.shutdown()?;
    Ok(())
}
```

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

### Configure OpenTelemetry SDK for Java

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-java.md

Initializes the OpenTelemetry SDK with OTLP HTTP exporter and custom resource attributes. Ensure the API key and endpoint are correctly set.

```java
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.semconv.ResourceAttributes;

public class Telemetry {
    public static OpenTelemetry init() {
        Resource resource = Resource.getDefault().merge(
            Resource.create(Attributes.builder()
                .put(ResourceAttributes.SERVICE_NAME, "my-java-app")
                .put(ResourceAttributes.DEPLOYMENT_ENVIRONMENT,
                    System.getenv().getOrDefault("DEPLOYMENT_ENV", "development"))
                .build())
        );

        OtlpHttpSpanExporter exporter = OtlpHttpSpanExporter.builder()
            .setEndpoint("https://ingest.maple.dev/v1/traces")
            .addHeader("Authorization", "Bearer YOUR_API_KEY")
            .build();

        SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
            .addSpanProcessor(BatchSpanProcessor.builder(exporter).build())
            .setResource(resource)
            .build();

        OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
            .setTracerProvider(tracerProvider)
            .buildAndRegisterGlobal();

        Runtime.getRuntime().addShutdownHook(new Thread(tracerProvider::close));

        return openTelemetry;
    }
}
```

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

### Log correlation within spans

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/sdks/effect.md

Logs emitted with `Effect.log` inside an active span are automatically correlated with the trace. No additional setup is required.

```typescript
const program = Effect.gen(function* () {
	yield* Effect.log("Processing started")
	yield* doWork()
	yield* Effect.log("Processing complete")
}).pipe(Effect.withSpan("process"))
```

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

### Use OTel slog Bridge for Log Correlation in Go

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-go.md

Install the otelslog bridge and use otelslog.NewLogger to send structured logs that are correlated with traces.

```bash
go get go.opentelemetry.io/contrib/bridges/otelslog
```

```go
import "go.opentelemetry.io/contrib/bridges/otelslog"

logger := otelslog.NewLogger("my-app")
logger.InfoContext(ctx, "Order processed", "order_id", orderID)
```

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

### Configure Java Agent with JVM Args

Source: https://github.com/makisuo/maple/blob/main/skills/maple-java-style/SKILL.md

Run the Java application with the agent, specifying service name, OTLP protocol, endpoint, and ingest key as JVM arguments.

```bash
java \
  -javaagent:./opentelemetry-javaagent.jar \
  -Dotel.service.name=orders-api \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.endpoint=https://ingest.maple.dev \
  -Dotel.exporter.otlp.headers="authorization=Bearer MAPLE_TEST" \
  -Dotel.resource.attributes="vcs.repository.url.full=https://github.com/acme/orders-api,vcs.ref.head.revision=${GITHUB_SHA:-}" \
  -jar build/libs/app.jar
```

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

### Wire OpenTelemetry Initialization in main

Source: https://github.com/makisuo/maple/blob/main/skills/maple-go-style/SKILL.md

Call the telemetry initialization function from your main application entry point and ensure the shutdown function is deferred.

```go
func main() {
	ctx := context.Background()
	shutdown, err := telemetry.Init(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer shutdown(ctx)

	// app start
}

```

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

### Create LLM Client Message

Source: https://github.com/makisuo/maple/blob/main/skills/maple-onboarding-style/SKILL.md

Example of creating a message with an LLM client. Ensure provider instrumentation captures model, provider, and token spans.

```typescript
const response = await client.messages.create({
	model,
	max_tokens: 100,
	messages,
})
```

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

### Run All Apps with Bun Dev

Source: https://github.com/makisuo/maple/blob/main/CLAUDE.md

Use this command to run all applications within the project using Bun and Turbo. Each app's `dev` script will invoke portless URLs.

```bash
bun dev
```

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

### Initialize OpenTelemetry SDK

Source: https://github.com/makisuo/maple/blob/main/skills/maple-java-style/SKILL.md

Programmatically initialize the OpenTelemetry SDK with OTLP HTTP exporters, service name, and resource attributes.

```java
public final class Telemetry {
    private static final String MAPLE_ENDPOINT = "https://ingest.maple.dev";
    private static final String MAPLE_KEY = "MAPLE_TEST"; // set by maple-onboard skill on pairing

    public static OpenTelemetrySdk init() {
        var headers = Map.of("authorization", "Bearer " + MAPLE_KEY);
        var resource = Resource.getDefault().merge(Resource.create(Attributes.builder()
            .put(ServiceAttributes.SERVICE_NAME, "orders-api")
            .put(DeploymentIncubatingAttributes.DEPLOYMENT_ENVIRONMENT_NAME,
                System.getenv().getOrDefault("DEPLOYMENT_ENV", "development"))
            .put("vcs.repository.url.full", "https://github.com/acme/orders-api")
            .put("vcs.ref.head.revision", System.getenv().getOrDefault("GITHUB_SHA", ""))
            .build()));

        var spanExporter = OtlpHttpSpanExporter.builder()
            .setEndpoint(MAPLE_ENDPOINT + "/v1/traces")
            .setHeaders(() -> headers)
            .build();
        // … same shape for OtlpHttpLogRecordExporter and OtlpHttpMetricExporter

        return OpenTelemetrySdk.builder()
            .setTracerProvider(SdkTracerProvider.builder()
                .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
                .setResource(resource)
                .build())
            .buildAndRegisterGlobal();
    }
}
```

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

### WhereClause Example - Corrected

Source: https://github.com/makisuo/maple/blob/main/skills/maple-dashboard-widgets/SKILL.md

Demonstrates the correct syntax for the custom `whereClause` grammar, specifically using `exists` to check for attribute presence instead of `IS NOT NULL`.

```plaintext
service.name = "ingest" AND maple.signal exists
```

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

### Deploy Maple OTel Collector with Helm

Source: https://github.com/makisuo/maple/blob/main/docs/self-hosted-clickhouse.md

Install the Maple OpenTelemetry Collector on Kubernetes using the provided Helm chart. Configure the ClickHouse endpoint and password.

```bash
helm install maple-otel oci://ghcr.io/makisuo/charts/maple-otel \
  --namespace maple --create-namespace \
  --set maple.orgId=org_xxx \
  --set maple.clickhouse.endpoint=https://your-ch.example.com \
  --set maple.clickhouse.password.value=$CH_PASSWORD
```

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

### Configure OpenTelemetry SDK for Console Apps

Source: https://github.com/makisuo/maple/blob/main/apps/landing/src/content/docs/guides/instrumentation-csharp.md

Set up the OpenTelemetry provider directly for non-ASP.NET Core applications like console apps or workers. This example demonstrates building a tracer provider with resource configuration, source addition, HTTP client instrumentation, and an OTLP exporter.

```csharp
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .ConfigureResource(r => r.AddService("my-dotnet-worker"))
    .AddSource("my-dotnet-worker")
    .AddHttpClientInstrumentation()
    .AddOtlpExporter(opts =>
    {
        opts.Endpoint = new Uri("https://ingest.maple.dev/v1/traces");
        opts.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;
        opts.Headers = "Authorization=Bearer YOUR_API_KEY";
    })
    .Build();
```

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

### Define ClickHouse Migration

Source: https://github.com/makisuo/maple/blob/main/docs/self-hosted-clickhouse.md

Example of a TypeScript migration file to add a new column to a ClickHouse table. Use this pattern for schema evolution in self-hosted ClickHouse.

```typescript
export const migration_0002_add_foo_column = {
  version: 2,
  description: "Add Foo column to traces",
  statements: [
    "ALTER TABLE traces ADD COLUMN IF NOT EXISTS Foo String DEFAULT ''",
    "ALTER TABLE traces MATERIALIZE COLUMN Foo",
  ],
} as const
```

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

### Run Node.js App with Telemetry Bootstrap

Source: https://github.com/makisuo/maple/blob/main/skills/maple-nodejs-style/SKILL.md

Execute your Node.js application with the telemetry script loaded first using the --import flag.

```bash
node --import ./telemetry.js app.js
```

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

### Bootstrap OpenTelemetry in ASP.NET Core

Source: https://github.com/makisuo/maple/blob/main/skills/maple-csharp-style/SKILL.md

Configure OpenTelemetry for traces, metrics, and logs within the .NET hosting model. This example inlines the Maple endpoint and ingest key.

```csharp
using OpenTelemetry;
using OpenTelemetry.Exporter;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

const string MapleEndpoint = "https://ingest.maple.dev";
const string MapleKey = "MAPLE_TEST"; // set by maple-onboard skill on pairing

var builder = WebApplication.CreateBuilder(args);

void ConfigureOtlp(OtlpExporterOptions options, string path)
{
    options.Endpoint = new Uri($"{MapleEndpoint}/v1/{path}");
    options.Protocol = OtlpExportProtocol.HttpProtobuf;
    options.Headers = $"authorization=Bearer {MapleKey}";
}

var resource = ResourceBuilder.CreateDefault()
    .AddService("orders-api")
    .AddAttributes(new Dictionary<string, object>
    {
        ["deployment.environment.name"] = builder.Environment.EnvironmentName,
        ["vcs.repository.url.full"] = "https://github.com/acme/orders-api",
        ["vcs.ref.head.revision"] = Environment.GetEnvironmentVariable("GITHUB_SHA") ?? "",
    });

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("orders-api"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter(o => ConfigureOtlp(o, "traces")))
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter(o => ConfigureOtlp(o, "metrics")));

builder.Logging.AddOpenTelemetry(logging =>
{
    logging.SetResourceBuilder(resource);
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
    logging.AddOtlpExporter(o => ConfigureOtlp(o, "logs"));
});

var app = builder.Build();
```