Configuration

Configuration Reference

Complete configuration guide for LeanJ components.

Agent Configuration

Java Agent Arguments

Add agent to JVM startup:

-javaagent:dist/agent/agent-core-1.0.0-SNAPSHOT.jar=package=com.myapp

Parameters:

• package=<package> - Package prefix to instrument (required)

Example:

-javaagent:agent.jar=package=com.example

System Properties

Controller Connection

-Dprofiler.controller.host=localhost          # Controller host (default: localhost)
-Dprofiler.controller.port=9876              # Controller TCP port (default: 9876)
-Dprofiler.controller.http.port=9877        # Controller HTTP port (default: 9877)

Flush Interval

-Dprofiler.flush.interval.ms=1000            # Metrics flush interval in ms (default: 1000)

Timer Source

-Dprofiler.timer=wall                        # wall-clock time (default on Windows)
-Dprofiler.timer=cpu                         # CPU time

Note: Windows defaults to wall for better stability.

Environment Variables

Docker Registration

LEANJ_PROJECT=my-service             # Project name for identification
LEANJ_CONTROLLER_HOST=localhost      # Controller host
LEANJ_CONTROLLER_PORT=9876           # Controller TCP port

Complete Agent Configuration

VM Options:

-javaagent:dist/agent/agent-core-1.0.0-SNAPSHOT.jar=package=com.myapp
-Dprofiler.controller.host=localhost
-Dprofiler.controller.port=9876
-Dprofiler.controller.http.port=9877
-Dprofiler.flush.interval.ms=1000
-Dprofiler.timer=wall

Dockerfile:

ENV JAVA_TOOL_OPTIONS="-javaagent:/agent/agent.jar=package=com.myapp"
ENV LEANJ_PROJECT=my-service
ENV LEANJ_CONTROLLER_HOST=host.docker.internal
ENV LEANJ_CONTROLLER_PORT=9876

Controller Configuration

Ports

Default:

• TCP: 9876 (agent connections)
• HTTP: 9877 (CLI/IDE API)

Custom Ports:

CLI:

leanj controller start --port 8888
# TCP: 8887, HTTP: 8888

Environment Variable:

export LEANJ_CONTROLLER_PORT=8888
leanj controller start

Manual:

java -jar controller.jar 8887 8888
# TCP port, HTTP port

Resource Monitoring

System Property:

-Dprofiler.controller.resource.interval.seconds=10  # Monitoring interval (default: 10)

CLI Configuration

CLI Path

System Property (for IDE):

-Dleanj.cli.path=/path/to/leanj

Environment Variable:

export LEANJ_CLI_PATH=/usr/local/bin/leanj

Controller Port

Environment Variable:

export LEANJ_CONTROLLER_PORT=9877

License Configuration

API URL

Environment Variable:

export LEANJ_LICENSE_API_URL=https://license-api.leanj.com/v1

Default: Cloudflare Worker endpoint

Machine ID

Environment Variable:

export LEANJ_MACHINE_ID=abc123

Note: Auto-generated if not set. Used for license validation.

Development Mode

Environment Variable:

export LEANJ_DEV_MODE=true

Warning: Only for testing. Do not use in production.

Checkout URL

Environment Variable:

export LEMON_SQUEEZY_CHECKOUT_URL=https://your-store.lemonsqueezy.com/checkout/buy/variant-id

IntelliJ Plugin Configuration

CLI Path

VM Options:

-Dleanj.cli.path=C:\tools\leanj.exe

File: Help → Edit Custom VM Options...

Controller Port

Uses CLI configuration (environment variable or default).

Package Filtering

Single Package

-javaagent:agent.jar=package=com.myapp

Multiple Packages

Currently, only one package prefix is supported. For multiple packages, use a common parent:

# Instead of: com.foo, com.bar
# Use: com
-javaagent:agent.jar=package=com

Performance Tuning

Reduce Overhead

Increase flush interval:

-Dprofiler.flush.interval.ms=5000  # Flush every 5 seconds instead of 1

Note: Lower frequency = less overhead but less real-time updates.

Increase Precision

Decrease flush interval:

-Dprofiler.flush.interval.ms=500   # Flush every 500ms

Note: Higher frequency = more overhead but more real-time updates.

Network Configuration

Docker Desktop (Mac/Windows)

ENV LEANJ_CONTROLLER_HOST=host.docker.internal

Linux

Option 1: Host IP

ENV LEANJ_CONTROLLER_HOST=172.17.0.1

Option 2: Shared Network Use Docker network or Kubernetes service name.

Kubernetes

env:
- name: LEANJ_CONTROLLER_HOST
  value: "profiler-controller.default.svc.cluster.local"

Configuration Files

License Storage

Location: ~/.leanj/license.json

Format:

{
  "licenseKey": "abc123-def456",
  "tier": "pro",
  "expiresAt": "2025-12-31T23:59:59Z",
  "machineId": "xyz789"
}

Note: File is created automatically. Do not edit manually.

Controller PID File

Location: ~/.leanj/controller.pid

Note: Used for controller lifecycle management. Do not edit manually.

Configuration Examples

Local Development

Run Configuration (IntelliJ):

VM options:
-javaagent:dist/agent/agent-core-1.0.0-SNAPSHOT.jar=package=com.example
-Dprofiler.controller.host=localhost
-Dprofiler.controller.port=9876
-Dprofiler.timer=wall

Docker Development

Dockerfile:

FROM openjdk:11-jre-slim

COPY agent-core-1.0.0-SNAPSHOT.jar /agent/agent.jar

ENV JAVA_TOOL_OPTIONS="-javaagent:/agent/agent.jar=package=com.myapp"
ENV LEANJ_PROJECT=my-service
ENV LEANJ_CONTROLLER_HOST=host.docker.internal
ENV LEANJ_CONTROLLER_PORT=9876

Production

Minimal overhead:

-javaagent:agent.jar=package=com.myapp
-Dprofiler.flush.interval.ms=5000
-Dprofiler.timer=cpu

Real-time monitoring:

-javaagent:agent.jar=package=com.myapp
-Dprofiler.flush.interval.ms=500
-Dprofiler.timer=wall

Troubleshooting

Agent Not Connecting

Check:

1. Controller host/port configuration
2. Network connectivity
3. Firewall rules
4. Controller logs

High Overhead

Solutions:

1. Increase flush interval
2. Use CPU timer instead of wall-clock
3. Narrow package filter

Configuration Not Applied

Check:

1. System properties format
2. Environment variables set correctly
3. JVM restarted (if needed)
4. Configuration precedence

Next Steps

• Learn about CLI commands
• Read How It Works
• See Troubleshooting Guide