Skip to content

ExtensionConfiguration.md

Latest commit

 

History

History
155 lines (112 loc) · 4.36 KB

ExtensionConfiguration.md

File metadata and controls

155 lines (112 loc) · 4.36 KB
Raw

BTrace Extension Configuration

Overview

Extension configuration allows users to customize extension loading behavior, enable/disable specific extensions, and pass extension-specific settings.

Configuration File Locations

Configuration files are searched in priority order (highest to lowest):

  1. Command-line override: -Dbtrace.extensions.config=/path/to/config
  2. User config: ~/.btrace/extensions.conf
  3. System config: $BTRACE_HOME/conf/extensions.conf

The first file found is used. Settings from multiple files are NOT merged.

Configuration Format

Uses standard Java properties format:

# Extension Control
# Comma-separated list of extension IDs to enable (empty = all enabled)
extensions.enabled=

# Comma-separated list of extension IDs to disable
extensions.disabled=

# Auto-load extensions on demand (default: true)
extensions.autoload=true

# Extension-specific settings (passed to extension on load)
# Format: <extension-id>.<setting-name>=<value>
btrace-metrics.histogram.default-precision=3
btrace-metrics.stats.window-size=1000

Configuration Properties

Global Settings

extensions.enabled

  • Format: comma-separated extension IDs
  • Default: (empty - all enabled)
  • Example: extensions.enabled=btrace-metrics,btrace-custom
  • Description: Whitelist of extensions to load. If set, only listed extensions are loaded. If empty or not set, all discovered extensions are enabled (unless explicitly disabled).

extensions.disabled

  • Format: comma-separated extension IDs
  • Default: (empty - none disabled)
  • Example: extensions.disabled=btrace-old-metrics
  • Description: Blacklist of extensions to prevent from loading. Takes precedence over extensions.enabled.

extensions.autoload

  • Format: boolean (true/false)
  • Default: true
  • Description: If true, extensions are loaded on demand when scripts use their services. If false, all enabled extensions are loaded at agent startup.

Extension-Specific Settings

Extensions can define custom configuration properties using the pattern:

<extension-id>.<setting-name>=<value>

Examples:

# BTrace Metrics settings
btrace-metrics.histogram.default-precision=3
btrace-metrics.histogram.max-value=3600000000
btrace-metrics.stats.window-size=1000

# Custom extension settings
my-extension.feature.enabled=true
my-extension.endpoint=http://localhost:8080

Extension-specific settings are passed to the extension when loaded. Extensions can access these via their configuration API.

Usage Examples

Example 1: Disable Specific Extension

# Disable legacy metrics extension
extensions.disabled=btrace-old-metrics

Example 2: Whitelist Extensions

# Only load metrics and custom extensions
extensions.enabled=btrace-metrics,my-custom-extension

Example 3: Configure Extension Settings

# Configure metrics extension
btrace-metrics.histogram.default-precision=3
btrace-metrics.histogram.max-value=3600000000

Example 4: Load All Extensions at Startup

# Disable lazy loading, load all extensions immediately
extensions.autoload=false

API Integration

ExtensionConfig Class

New class to manage extension configuration:

public class ExtensionConfig {
  public boolean isEnabled(String extensionId);
  public boolean isAutoLoad();
  public Properties getExtensionProperties(String extensionId);
}

ExtensionLoader Integration

ExtensionLoader will:

  1. Load configuration on initialization
  2. Filter discovered extensions based on enabled/disabled lists
  3. Apply autoload setting (lazy vs eager loading)
  4. Pass extension-specific properties when loading extensions

Configuration Loading Priority

Command-line (-Dbtrace.extensions.config)
    ↓
User config (~/.btrace/extensions.conf)
    ↓
System config ($BTRACE_HOME/conf/extensions.conf)
    ↓
Built-in defaults (all enabled, autoload=true)

Backward Compatibility

  • If no configuration file exists, all extensions are enabled with autoload
  • Existing deployments continue to work without any configuration
  • Configuration is purely additive (opt-in customization)

Future Enhancements

  • Hot reload: Detect configuration file changes and reload extensions
  • JMX integration: Expose extension configuration via JMX for runtime modification
  • Validation: Warn about unknown extension IDs or malformed settings