Cameleer

Observability platform for Apache Camel applications. Two integration modes: a Java agent (-javaagent) for zero-code instrumentation, or a Quarkus extension for CDI-based instrumentation with GraalVM native image support.

Architecture

cameleer-common           Shared models + graph API
        |
cameleer-core             Observability logic (collector, notifier, exporter, metrics, diagrams)
       / \
      /   \
cameleer-agent            cameleer-extension (runtime + deployment)
(ByteBuddy instrumentation) (CDI lifecycle hooks, GraalVM native support)
      |                          |
      |--- attaches to -------+  |--- compiled into ------+
      |                       |  |                         |
sample-app  backend-app  caller-app  quarkus-app  quarkus-native-app
(Spring Boot)                        (Quarkus)    (Quarkus, no agent)

Quick Start

Build

mvn clean package -DskipTests

Option 1: Java Agent (any Camel app)

Attach the shaded agent JAR to any Camel application — Spring Boot, Quarkus (JVM mode), or standalone:

java -javaagent:cameleer-agent/target/cameleer-agent-1.0-SNAPSHOT-shaded.jar \
     -jar your-camel-app.jar

Option 2: Quarkus Extension (Quarkus apps, including native)

Add the extension dependency to your Quarkus project:

<dependency>
    <groupId>com.cameleer</groupId>
    <artifactId>cameleer-extension</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Configure in application.properties:

cameleer.agent.export.type=HTTP
cameleer.agent.export.endpoint=http://cameleer-server:8081
cameleer.agent.application=my-app

No -javaagent flag needed. Works in JVM and GraalVM native mode.

Run Example Apps

# Spring Boot sample app (agent mode)
java -javaagent:cameleer-agent/target/cameleer-agent-1.0-SNAPSHOT-shaded.jar \
     -jar cameleer-sample-app/target/cameleer-sample-app-1.0-SNAPSHOT.jar

# Quarkus sample app (agent mode, uber-jar)
java -javaagent:cameleer-agent/target/cameleer-agent-1.0-SNAPSHOT-shaded.jar \
     -jar cameleer-quarkus-app/target/cameleer-quarkus-app-1.0-SNAPSHOT-runner.jar

# Quarkus native app (extension mode, no agent, uber-jar)
java -jar cameleer-quarkus-native-app/target/cameleer-quarkus-native-app-1.0-SNAPSHOT-runner.jar

Test REST Endpoint

curl -X POST http://localhost:8080/api/orders \
  -H "Content-Type: application/json" \
  -d '{"orderId":"123","type":"PRIORITY","amount":99.99}'

What You Get

• Route monitoring — execution chunks for every route execution with timing, status, correlation
• Processor tracing — flat processor records with seq/parentSeq parent-child relationships
• Payload capture — exchange-level input/output snapshots (REGULAR+) and per-processor body/headers/properties (COMPLETE)
• Error tracking — classified errors (TIMEOUT/CONNECTION/VALIDATION/SECURITY/RESOURCE) with full stack traces
• Metrics bridge — Camel JMX statistics in periodic summaries (JVM mode only)
• Prometheus endpoint — /metrics HTTP endpoint for scraping
• Route graphs — JSON graph models of every route's topology (nodes, edges, EIP patterns)
• Cross-service correlation — X-Cameleer-CorrelationId header propagation across services
• Taps — runtime business attribute extraction via Camel expression languages
• Replay — synchronous exchange replay with audit trail
• Route control — dynamic start/stop/suspend/resume of routes
• Route state reporting — real-time route state (Started/Stopped/Suspended) via heartbeat and state change events
• Log forwarding — Logback, Log4j2, and JUL log forwarding to the server
• OpenTelemetry — hybrid OTel integration (OFF/AUTO/CREATE/CORRELATE modes)
• Auto-recovery — re-registers with full capabilities on 404 (server data loss), refreshes JWT on 401/403

Configuration

System properties with cameleer.agent. prefix (agent mode) or application.properties entries (extension mode):

Property	Default	Description
cameleer.agent.enabled	true	Master on/off
cameleer.agent.export.type	LOG	LOG or HTTP
cameleer.agent.export.endpoint		Server URL (for HTTP export)
cameleer.agent.application	default	Application identifier
cameleer.agent.environment	default	Environment identifier (dev/staging/prod)
cameleer.agent.instanceid		Optional instance ID override (default: {hostname}-{pid})
cameleer.agent.engine.level	REGULAR	NONE, MINIMAL, REGULAR, COMPLETE
cameleer.agent.payload.capture	BOTH	NONE, INPUT, OUTPUT, BOTH
cameleer.agent.payload.maxsize	4096	Max payload bytes
cameleer.agent.payload.sensitiveheaders	Authorization,Cookie,Set-Cookie,X-API-Key,X-Auth-Token,Proxy-Authorization	Headers to mask
cameleer.agent.payload.sensitiveproperties	(empty)	Exchange properties to mask
cameleer.agent.metrics.enabled	true	Bridge Camel JMX metrics
cameleer.agent.metrics.interval	60	Metrics summary interval (seconds)
cameleer.agent.prometheus.enabled	false	Prometheus /metrics endpoint
cameleer.agent.prometheus.port	9464	Prometheus endpoint port
cameleer.agent.diagram.enabled	true	Extract route graph models
cameleer.agent.diagram.outputdir	./cameleer-diagrams	Graph JSON output directory
cameleer.agent.diagram.debugsvg	false	Generate debug SVG files
cameleer.agent.sampling.rate	1.0	Global sampling rate (0.0-1.0)
cameleer.agent.routecontrol.enabled	false	Enable dynamic route control
cameleer.agent.replay.enabled	false	Enable exchange replay
cameleer.agent.taps.enabled	true	Enable business attribute extraction
cameleer.agent.logs.enabled	true	Enable log forwarding
cameleer.agent.otel.mode	OFF	OpenTelemetry mode: OFF, AUTO, CREATE, CORRELATE
cameleer.agent.execution.compresssuccess	false	Strip processor records from successful executions
cameleer.agent.health.enabled	true	Enable health endpoint

Example with custom config:

java -Dcameleer.agent.payload.capture=INPUT \
     -Dcameleer.agent.export.type=HTTP \
     -Dcameleer.agent.export.endpoint=http://localhost:8081 \
     -Dcameleer.agent.prometheus.enabled=true \
     -javaagent:cameleer-agent/target/cameleer-agent-1.0-SNAPSHOT-shaded.jar \
     -jar cameleer-sample-app/target/cameleer-sample-app-1.0-SNAPSHOT.jar

Modules

cameleer/
├── cameleer-common/              Shared models + graph API
├── cameleer-core/                Observability logic (no ByteBuddy) + PostStartSetup
│   ├── collector/                 Execution collection + payload capture
│   ├── notifier/                  EventNotifier + InterceptStrategy
│   ├── export/                    Log + HTTP (chunked) exporters
│   ├── connection/                Server connection, SSE, heartbeat
│   ├── command/                   SSE command handling
│   ├── config/                    Config cache management
│   ├── diagram/                   Route model extraction + debug SVG
│   ├── metrics/                   Camel JMX metrics + Prometheus
│   ├── tap/                       Business attribute extraction
│   ├── otel/                      OpenTelemetry bridge
│   ├── health/                    Health endpoint + startup report
│   └── logging/                   Log forwarding (Logback, Log4j2, JUL)
├── cameleer-agent/               Java agent (ByteBuddy instrumentation)
│   ├── instrumentation/           ByteBuddy advice + transformer
│   └── logging/                   ByteBuddy-injected log appenders
├── cameleer-extension/           Quarkus extension
│   ├── runtime/                   CDI lifecycle hooks → core
│   └── deployment/                Build-time processing (reflection registration)
├── cameleer-sample-app/          Spring Boot + Camel (11 route classes)
├── cameleer-backend-app/         REST product service (cross-service demo)
├── cameleer-caller-app/          HTTP caller (cross-service correlation demo)
├── cameleer-quarkus-app/         Quarkus + Camel Quarkus (5 route classes)
├── cameleer-quarkus-native-app/  Quarkus with extension (GraalVM-ready)
└── docs/                          Architecture + design documentation

Requirements

• Java 17+
• Maven 3.9+
• Apache Camel 4.10.x (target application)
• Quarkus 3.33+ (for extension mode, Camel Quarkus 3.11 minimum)