Agent-Side Configuration | Medplum

Configuration Parameters

The Medplum Agent requires four essential parameters to connect to your Medplum server:

Parameter	Description	Required
`baseUrl`	The Medplum server base URL (e.g., `https://api.medplum.com`)	Yes
`clientId`	The OAuth client ID from your ClientApplication	Yes
`clientSecret`	The OAuth client secret from your ClientApplication	Yes
`agentId`	The UUID of your Agent resource	Yes

Optional Parameters

Parameter	Description	Default
`logLevel`	Global log level for both main and channel loggers	`INFO`
`logger.main.*`	Configuration for the main logger	-
`logger.channel.*`	Configuration for the channel logger	-

Configuration Methods

There are two ways to configure the Medplum Agent: via command line arguments or using an agent.properties file.

Command Line Arguments

When running the agent from the command line, provide the required parameters as arguments:

npm run agent <baseUrl> <clientId> <clientSecret> <agentId> [logLevel]

Example:

npm run agent https://api.medplum.com my-client-id my-client-secret 123e4567-e89b-12d3-a456-426614174000

Example with log level:

npm run agent https://api.medplum.com my-client-id my-client-secret 123e4567-e89b-12d3-a456-426614174000 DEBUG

Environment Variable Configuration

When running the agent in Docker or other containerized environments, you can use the MEDPLUM_LOG_LEVEL environment variable to set the global log level:

docker run -e MEDPLUM_LOG_LEVEL="DEBUG" \
  -e MEDPLUM_BASE_URL="https://api.medplum.com" \
  -e MEDPLUM_CLIENT_ID="my-client-id" \
  -e MEDPLUM_CLIENT_SECRET="my-client-secret" \
  -e MEDPLUM_AGENT_ID="123e4567-e89b-12d3-a456-426614174000" \
  medplum/medplum-agent:latest

Properties File Configuration

The agent.properties file provides full access to all configuration options, including advanced logger settings.

File Location

Windows: C:\Program Files\Medplum Agent\agent.properties
Linux/macOS: In the directory where the agent is installed (typically the same directory as the agent executable)

File Format

The properties file uses a simple key=value format with one setting per line:

baseUrl=https://api.medplum.com
clientId=my-client-id
clientSecret=my-client-secret
agentId=123e4567-e89b-12d3-a456-426614174000

Setting Global Log Level

To set the same log level for both main and channel loggers, use the logLevel parameter in agent.properties:

logLevel=DEBUG

Logger Configuration

The Medplum Agent uses two separate, independently configurable loggers to provide fine-grained control over logging and to protect patient privacy.

Main Logger vs. Channel Logger

Main Logger

The main logger records general agent activity, including:

Agent startup and shutdown events
Connection status to the Medplum server
Configuration warnings and errors
General system exceptions
Agent lifecycle events

Important: The main logger does not contain Protected Health Information (PHI).

Channel Logger

The channel logger records activity specific to individual communication channels, including:

HL7 message content and processing
DICOM study transfers
ASTM result messages
Channel-specific errors and warnings
Message routing and transformation

Important: The channel logger may contain PHI as it logs the actual content of messages being transmitted.

Logger Configuration Properties

Each logger (main and channel) supports the following configuration properties:

Property	Type	Default	Description
`logLevel`	string	`INFO`	Log verbosity level: `NONE`, `ERROR`, `WARN`, `INFO`, or `DEBUG`
`logDir`	string	Agent directory	Directory path where log files are stored
`maxFileSizeMb`	integer	`10`	Maximum log file size in megabytes before rotation
`filesToKeep`	integer	`10`	Number of rotated log files to retain

Configuration Syntax

To configure a logger property, use the format:

logger.<type>.<property>=<value>

Where:

<type> is either main or channel
<property> is one of: logLevel, logDir, maxFileSizeMb, filesToKeep
<value> is the desired setting

Configuration Examples

Example 1: Different Log Levels

Set the main logger to INFO and increase the channel logger to DEBUG for detailed message debugging:

logger.main.logLevel=INFO
logger.channel.logLevel=DEBUG

Example 2: Separate Log Directories

Store main and channel logs in separate directories for easier management and access control:

Linux/macOS:

logger.main.logDir=/var/log/medplum-agent
logger.channel.logDir=/var/log/medplum-agent/channels

Windows:

logger.main.logDir=C:\Logs\MedplumAgent
logger.channel.logDir=C:\Logs\MedplumAgent\Channels

Example 3: Different Retention Policies

Keep more channel logs for compliance, but limit main logs to conserve space:

logger.main.maxFileSizeMb=10
logger.main.filesToKeep=5
logger.channel.maxFileSizeMb=50
logger.channel.filesToKeep=30

Example 4: Production Configuration

A production configuration that separates PHI-containing logs to a separate directory:

baseUrl=https://api.medplum.com
clientId=production-client-id
clientSecret=production-client-secret
agentId=production-agent-id

# Main logger: INFO level, moderate retention
logger.main.logLevel=INFO
logger.main.logDir=/var/log/medplum/main
logger.main.maxFileSizeMb=10
logger.main.filesToKeep=10

# Channel logger: WARN level (only warnings and errors), extended retention
logger.channel.logLevel=INFO
logger.channel.logDir=/var/log/medplum/channels
logger.channel.maxFileSizeMb=20
logger.channel.filesToKeep=60

Log File Names

Logs are written to daily-rotated files with the following naming conventions:

Main logger: medplum-agent-main-YYYY-MM-DD.log
Channel logger: medplum-agent-channels-YYYY-MM-DD.log

Verifying Logger Configuration

After restarting the agent, you can verify the log level is set correctly by examining the log output. Each log entry includes a level field in the JSON structure:

{ "level": "INFO", "msg": "Successfully connected to Medplum server", "timestamp": "2024-10-02T16:52:56.789Z" }

Resetting to Defaults

To reset logger configuration to defaults, remove the corresponding properties from agent.properties and restart the agent service.