Configuration

This guide covers all configuration options available in Project Argus.

Agent Configuration

The Argus agent is configured via Java system properties.

Available Properties

Core Settings

Property	Default	Description
`argus.server.enabled`	`false`	Enable built-in dashboard server
`argus.server.port`	`9202`	WebSocket server port
`argus.buffer.size`	`65536`	Ring buffer size for event collection

GC & Memory Settings

Property	Default	Description
`argus.gc.enabled`	`true`	Enable GC monitoring
`argus.allocation.enabled`	`false`	Enable allocation rate tracking (high overhead)
`argus.allocation.threshold`	`1048576`	Minimum allocation size to track (1MB)
`argus.metaspace.enabled`	`true`	Enable metaspace monitoring

CPU & Performance Settings

Property	Default	Description
`argus.cpu.enabled`	`true`	Enable CPU monitoring
`argus.cpu.interval`	`1000`	CPU sampling interval (ms)
`argus.profiling.enabled`	`false`	Enable method profiling (high overhead)
`argus.profiling.interval`	`20`	Method profiling sampling interval (ms)
`argus.contention.enabled`	`false`	Enable lock contention tracking
`argus.contention.threshold`	`50`	Minimum contention duration to track (ms)

Analysis Settings

Property	Default	Description
`argus.correlation.enabled`	`true`	Enable correlation analysis

Metrics Export Settings

Property	Default	Description
`argus.metrics.prometheus.enabled`	`true`	Enable `/prometheus` endpoint
`argus.otlp.enabled`	`false`	Enable OTLP metrics push export
`argus.otlp.endpoint`	`http://localhost:4318/v1/metrics`	OTLP collector endpoint
`argus.otlp.interval`	`15000`	OTLP push interval (ms)
`argus.otlp.headers`	(empty)	Auth headers (`key=val,key=val`)
`argus.otlp.service.name`	`argus`	OTLP resource service name

Setting Properties

java -javaagent:argus-agent.jar \
     -Dargus.server.port=9090 \
     -Dargus.buffer.size=131072 \

     -jar your-application.jar

Buffer Size Tuning

The ring buffer size affects memory usage and event handling capacity.

Guidelines

Application Type	Recommended Size	Memory Usage
Development/Testing	`16384`	~1 MB
Standard Production	`65536` (default)	~4 MB
High-throughput	`131072`	~8 MB
Extreme throughput	`262144`	~16 MB

Considerations

Buffer size must be a power of 2
Larger buffers reduce the chance of event loss under high load
Smaller buffers use less memory

# High-throughput configuration
java -javaagent:argus-agent.jar \
     -Dargus.buffer.size=262144 \

     -jar high-traffic-app.jar

GC Monitoring Configuration

GC monitoring captures garbage collection events and heap usage.

# Enable/disable GC monitoring
java -javaagent:argus-agent.jar \
     -Dargus.gc.enabled=true \

     -jar your-application.jar

GC Events Captured

Event	Description
`jdk.GarbageCollection`	GC pause duration, cause, collector name
`jdk.GCHeapSummary`	Heap used/committed before and after GC

GC Metrics Available

Total GC events count
Total/Average/Max pause time
GC cause distribution
Recent GC history (last 20 events)
Current heap usage

CPU Monitoring Configuration

CPU monitoring tracks JVM and system CPU utilization.

# Configure CPU monitoring
java -javaagent:argus-agent.jar \
     -Dargus.cpu.enabled=true \
     -Dargus.cpu.interval=1000 \

     -jar your-application.jar

CPU Metrics Available

JVM CPU (user + system)
System CPU
Historical data (60-second rolling window)
Peak CPU values

Adjusting CPU Sampling Interval

# Sample every 500ms for more granular data
-Dargus.cpu.interval=500

# Sample every 2 seconds for lower overhead
-Dargus.cpu.interval=2000

Allocation Tracking Configuration

Allocation tracking monitors object allocation rate and identifies top allocating classes.

# Configure allocation tracking
java -javaagent:argus-agent.jar \
     -Dargus.allocation.enabled=true \
     -Dargus.allocation.threshold=1024 \

     -jar your-application.jar

Allocation Metrics Available

Total allocation count
Total bytes allocated
Allocation rate (MB/sec)
Peak allocation rate
Top 10 allocating classes

Tuning Allocation Threshold

# Track all allocations >= 512 bytes
-Dargus.allocation.threshold=512

# Track only large allocations >= 8KB
-Dargus.allocation.threshold=8192

Metaspace Monitoring Configuration

Metaspace monitoring tracks class metadata memory usage.

# Enable/disable metaspace monitoring
java -javaagent:argus-agent.jar \
     -Dargus.metaspace.enabled=true \

     -jar your-application.jar

Metaspace Metrics Available

Current used/committed memory
Peak usage
Growth rate (MB/min)
Class count

Method Profiling Configuration

Method profiling identifies CPU-intensive methods using execution sampling.

Warning: Method profiling has higher overhead. Use with caution in production.

# Enable method profiling
java -javaagent:argus-agent.jar \
     -Dargus.profiling.enabled=true \
     -Dargus.profiling.interval=20 \

     -jar your-application.jar

Method Profiling Metrics Available

Total sample count
Top 20 hot methods
Method sample percentage

Adjusting Profiling Interval

# More frequent sampling (higher accuracy, higher overhead)
-Dargus.profiling.interval=10

# Less frequent sampling (lower accuracy, lower overhead)
-Dargus.profiling.interval=50

Lock Contention Configuration

Lock contention tracking monitors thread synchronization bottlenecks.

# Configure contention tracking
java -javaagent:argus-agent.jar \
     -Dargus.contention.enabled=true \
     -Dargus.contention.threshold=10 \

     -jar your-application.jar

Contention Metrics Available

Total contention events
Total contention time
Top 10 contention hotspots
Per-thread contention time

Tuning Contention Threshold

# Track contention >= 5ms
-Dargus.contention.threshold=5

# Track only severe contention >= 50ms
-Dargus.contention.threshold=50

Correlation Analysis Configuration

Correlation analysis detects relationships between different metrics.

# Enable/disable correlation analysis
java -javaagent:argus-agent.jar \
     -Dargus.correlation.enabled=true \

     -jar your-application.jar

Correlation Features

GC ↔ CPU Correlation: Detects CPU spikes within 1 second of GC events
GC ↔ Pinning Correlation: Identifies pinning increases during GC
Automatic Recommendations: Provides actionable insights:
- GC overhead warnings (> 10%)
- Memory leak detection (sustained heap growth)
- Lock contention hotspot alerts
- High allocation rate warnings
- Metaspace growth warnings

JFR Event Configuration

Argus captures the following JFR events by default:

Virtual Thread Events

Event	Description	Overhead
`jdk.VirtualThreadStart`	Thread creation	Low
`jdk.VirtualThreadEnd`	Thread termination	Low
`jdk.VirtualThreadPinned`	Thread pinning (with stack trace)	Medium
`jdk.VirtualThreadSubmitFailed`	Submit failures	Low

GC & Memory Events

Event	Description	Overhead
`jdk.GarbageCollection`	GC pause events	Low
`jdk.GCHeapSummary`	Heap usage snapshots	Low
`jdk.ObjectAllocationInNewTLAB`	Object allocation in TLAB	Medium
`jdk.MetaspaceSummary`	Metaspace usage	Low

CPU & Performance Events

Event	Description	Overhead
`jdk.CPULoad`	CPU utilization (periodic)	Low
`jdk.ExecutionSample`	Method execution sampling	Medium-High
`jdk.JavaMonitorEnter`	Lock acquisition contention	Low
`jdk.JavaMonitorWait`	Lock wait contention	Low

JFR Settings

The agent configures JFR with:

Max Age: 10 seconds (sliding window)
Max Size: 10 MB

Server Configuration

Port Configuration

# Start server on custom port
java -Dargus.server.port=9090 -jar argus-server.jar

Production Deployment

For production environments, consider:

Bind to localhost only (for security):

# Use a reverse proxy (nginx, etc.) for external access

Enable TLS via reverse proxy:

# nginx configuration example
server {
    listen 443 ssl;
    server_name argus.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /events {
        proxy_pass http://localhost:9202;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /health {
        proxy_pass http://localhost:9202;
    }
}

Environment Variables

You can also use environment variables (converted to system properties):

export ARGUS_SERVER_PORT=9090
export ARGUS_BUFFER_SIZE=131072

java -javaagent:argus-agent.jar \
     -Dargus.server.port=${ARGUS_SERVER_PORT} \
     -Dargus.buffer.size=${ARGUS_BUFFER_SIZE} \

     -jar your-application.jar

Docker Configuration

Dockerfile Example

FROM eclipse-temurin:21-jre

COPY argus-agent.jar /opt/argus/
COPY your-application.jar /app/

ENV ARGUS_PORT=9202
ENV ARGUS_BUFFER_SIZE=65536

EXPOSE ${ARGUS_PORT}

ENTRYPOINT ["java", \
    "-javaagent:/opt/argus/argus-agent.jar", \
    "-Dargus.server.port=${ARGUS_PORT}", \
    "-Dargus.buffer.size=${ARGUS_BUFFER_SIZE}", \
    "-jar", "/app/your-application.jar"]

Docker Compose Example

version: '3.8'

services:
  app:
    build: .
    ports:
      - "9202:9202"
    environment:
      - ARGUS_PORT=9202
      - ARGUS_BUFFER_SIZE=131072

Kubernetes Configuration

Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: your-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: your-app:latest
          env:
            - name: JAVA_TOOL_OPTIONS
              value: "-javaagent:/opt/argus/argus-agent.jar"
            - name: ARGUS_SERVER_PORT
              value: "9202"
            - name: ARGUS_BUFFER_SIZE
              value: "65536"
          ports:
            - containerPort: 9202
              name: argus
          livenessProbe:
            httpGet:
              path: /health
              port: argus
            initialDelaySeconds: 10
            periodSeconds: 5

Performance Tuning

Low Latency Configuration

java -javaagent:argus-agent.jar \
     -Dargus.buffer.size=32768 \
     -XX:+UseZGC \
     -XX:+ZGenerational \

     -jar latency-sensitive-app.jar

High Throughput Configuration

java -javaagent:argus-agent.jar \
     -Dargus.buffer.size=262144 \
     -XX:+UseParallelGC \

     -jar high-throughput-app.jar

Prometheus Endpoint

Prometheus metrics are exposed at /prometheus by default.

# Scrape metrics
curl http://localhost:9202/prometheus

Prometheus scrape config

scrape_configs:
  - job_name: 'argus'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9202']
    metrics_path: '/prometheus'

OTLP Export Configuration

OTLP export pushes metrics to an OpenTelemetry collector in OTLP JSON format. No OpenTelemetry SDK is required — Argus hand-codes the OTLP protocol.

java -javaagent:argus-agent.jar \
     -Dargus.otlp.enabled=true \
     -Dargus.otlp.endpoint=http://localhost:4318/v1/metrics \
     -Dargus.otlp.interval=15000 \
     -jar your-application.jar

With Authentication

java -javaagent:argus-agent.jar \
     -Dargus.otlp.enabled=true \
     -Dargus.otlp.endpoint=https://otel.example.com/v1/metrics \
     -Dargus.otlp.headers=Authorization=Bearer\ mytoken \
     -Dargus.otlp.service.name=my-service \
     -jar your-application.jar

Metrics Exported

All 30+ metrics available via Prometheus are also exported via OTLP:

Type	Examples
Gauge	`argus_virtual_threads_active`, `argus_cpu_jvm_percent`, `argus_heap_used_bytes`
Sum (monotonic)	`argus_virtual_threads_started_total`, `argus_gc_pause_time_seconds_total`

CLI Configuration

The Argus CLI provides unified JVM diagnostics with auto source detection.

First-time Setup

argus init

This creates ~/.argus/config.properties with your preferred language and defaults.

CLI Commands

argus ps                       # List running JVM processes
argus histo <pid>              # Heap object histogram
argus histo <pid> --top 50     # Top 50 entries
argus threads <pid>            # Thread dump summary
argus gc <pid>                 # GC statistics
argus gcutil <pid>             # GC generation utilization (jstat-style)
argus heap <pid>               # Heap memory usage
argus sysprops <pid>           # System properties (--filter supported)
argus vmflag <pid>             # VM flags (--filter, --set supported)
argus nmt <pid>                # Native memory tracking
argus classloader <pid>        # Class loader hierarchy
argus jfr <pid> start          # Start Flight Recorder
argus jfr <pid> check          # Check recording status
argus info <pid>               # JVM information
argus top                      # Real-time monitoring (requires agent)

Global Options

Option	Default	Description
`--source=auto\|agent\|jdk`	`auto`	Data source selection
`--no-color`	(off)	Disable ANSI colors
`--lang=en\|ko\|ja\|zh`	`en`	Output language
`--format=table\|json`	`table`	Output format
`--host HOST`	`localhost`	Agent host (for `top` and agent source)
`--port PORT`	`9202`	Agent port

Source Auto-detection

When --source=auto (default), the CLI:

Tries connecting to the Argus agent via HTTP
Falls back to JDK tools (jcmd) if agent is unavailable

Use --source=agent or --source=jdk to force a specific source.

JSON Output

All commands support --format=json for pipeline integration:

argus gc 12345 --format=json | jq '.heapUsed'
argus histo 12345 --format=json --top 10 > heap-snapshot.json

Config File

Stored at ~/.argus/config.properties:

lang=en
default.source=auto
color=true
format=table
default.port=9202

Next Steps

Architecture Overview - Understand the internal design
Troubleshooting - Common issues and solutions

Uh oh!

FilesExpand file tree

configuration.md

Latest commit

History