# 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:

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

**Example:**

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

**Example with log level:**

```bash
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:

```bash
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:

```properties
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`:

```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:

```text
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:

```properties
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:**

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

**Windows:**

```properties
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:

```properties
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:

```properties
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:

```json
{ "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.