A Cloud Foundry CLI plugin that parses ECS (Elastic Common Schema) formatted JSON logs from the Cloud Controller and displays them in a clear, human-readable text format.

This plugin provides the ecslogs command, which works similarly to the standard cf logs command but is specifically designed to handle and format ECS JSON logs.

• Go 1.21 or later
• Cloud Foundry CLI v6.7.0 or later

# Clone the repository
git clone https://github.com/garethjevans/cf-ecslogs-plugin.git
cd cf-ecslogs-plugin

# Build the plugin
make build

# Install the plugin
cf install-plugin -f bin/cf-ecslogs-plugin

# Download the latest release for your platform
# Then install it
cf install-plugin -f cf-ecslogs-plugin

Stream logs from your application in real-time:

cf ecslogs APP_NAME

This will continuously display logs as they are generated by your application.

Dump recent logs and exit:

cf ecslogs APP_NAME --recent

This displays the most recent logs and then exits.

• ECS JSON Parsing: Automatically detects and parses ECS formatted JSON logs
• Clear Text Output: Converts complex JSON logs into readable text format
• Color-coded Logs: ERROR (red), WARN (orange), INFO (green), DEBUG (blue), TRACE (dim grey)
• Streaming Support: Real-time log streaming (default behavior)
• Recent Logs: Dump recent logs with the --recent flag
• Error Handling: Gracefully handles both ECS JSON and traditional log formats
• Stack Trace Display: Shows stack traces when available in error logs
• Thread Tracking: Displays thread information for request tracing
• Logger Context: Shows which component generated each log

The plugin formats logs in the following way:

TIMESTAMP [SOURCE] LEVEL [Logger] {thread} message

Example:

⚫ 2026-01-22T17:21:36.260Z [APP/REV/47/PROC/WEB/0] TRACE [HandlerMethod] {http-nio-8080-exec-1} Invoking method
🔵 2026-01-22T17:21:36.274Z [APP/REV/47/PROC/WEB/0] DEBUG [FilterChainProxy] {http-nio-8080-exec-1} Securing GET
🟢 2026-01-22T17:21:36.280Z [APP/REV/47/PROC/WEB/0] INFO [DispatcherServlet] {http-nio-8080-exec-2} Request received
🟠 2026-01-22T17:21:36.300Z [APP/REV/47/PROC/WEB/0] WARN [CacheManager] {http-nio-8080-exec-2} Cache miss
🔴 2026-01-22T17:21:36.330Z [APP/REV/47/PROC/WEB/0] ERROR [PaymentService] {http-nio-8080-exec-3} Payment failed

Color Scheme:

• 🔴 ERROR - Red
• 🟠 WARN - Orange/Yellow
• 🟢 INFO - Green
• 🔵 DEBUG - Blue
• ⚫ TRACE - Dim Grey

For more details, see COLOR_SUPPORT.md. Stack Trace: at main.go:123 at runtime/proc.go:456

## ECS Log Structure

The plugin supports the following ECS fields:

- `@timestamp`: Log timestamp
- `message`: Log message
- `log.level`: Log level (INFO, ERROR, WARN, etc.)
- `process`: Process information (type, index, pid)
- `error`: Error details including stack traces
- `labels`: Additional metadata (app name, org, space, etc.)
- `service`, `cloud`, `host`: Infrastructure information

## Development

### Building

```bash
make build

make test

Note: On macOS, you may encounter a dyld: missing LC_UUID error when running tests. This is a known issue with Go test binaries on macOS. The plugin binary itself builds and runs correctly. If you encounter this issue, you can:

• Test the plugin manually by installing it and running it against a CF environment
• Build the binary with make build to verify compilation succeeds

make clean

To remove the plugin:

cf uninstall-plugin ECSLogsPlugin

If you get a "command not found" error after installation:

1. Verify the plugin is installed: cf plugins
2. Reinstall the plugin: cf install-plugin -f bin/cf-ecslogs-plugin

If logs are not being formatted correctly:

• The plugin automatically falls back to displaying raw logs if they're not in ECS JSON format
• Check that your application is emitting logs in ECS JSON format

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.