Custom log files

The agent only sends the log files you list. You list them in service files: small YAML files, one per service, in the services folder.

OS	Folder
Linux	/etc/logcore-agent/services/
Windows	C:\ProgramData\Logcore\services\

/etc/logcore-agent/
├── logcore.yaml
└── services/
    ├── nginx.yaml            ← active
    ├── payments.yaml         ← active
    └── myapp.yaml.example    ← ignored (examples end in .example)

The agent reads every *.yaml and *.yml file in this folder. It ignores files ending in .example and hidden files (names starting with .).

The minimum

Only name and path are required:

# /etc/logcore-agent/services/nginx.yaml
name: nginx
path: /var/log/nginx/*.log

If you leave out name, the file name is used (nginx.yaml becomes nginx). Service names must be unique on a server.

Apply your changes

After you add or edit a service file:

Linux

sudo logcore-agent configcheck          # validates the files and lists the log files each service matches
sudo systemctl restart logcore-agent
sudo logcore-agent status               # the service should show [OK]

Windows

logcore-agent configcheck
logcore-agent service restart
logcore-agent status

Existing content

Only lines written after the agent starts following a file are sent. To import a file's existing content when it's first found, set logs.start_position: beginning in logcore.yaml.

All options

name: payments                     # service name in Logcore
paths:                             # one or more absolute paths (or use `path:` for one)
  - /var/log/payments/*.log
  - /opt/payments/logs/**/*.log
exclude_paths:                     # files to skip
  - "*.gz"
  - /var/log/payments/debug.log

include:                           # keep ONLY lines matching at least one regex
  - 'ERROR|WARN|Exception'
exclude:                           # drop lines matching any regex (checked first)
  - 'healthcheck'

tags: ["team:payments", "tier:1"]  # extra tags on this service's logs

multiline:                         # join multi-line events such as stack traces
  pattern: '^\d{4}-\d{2}-\d{2}'    # a new event starts with a date
  max_lines: 500
  timeout: 2s

status:                            # how severity is decided
  detect: auto                     # auto | none
  default: info                    # used when nothing else matches
  overrides:
    - match: 'OutOfMemory|deadlock'
      status: critical

Option	Required	Description
name	yes, or the file name	Service name shown in Logcore.
path / paths	yes	Absolute file paths. Wildcards are allowed.
exclude_paths		Patterns of files to skip.
include		Regexes. If set, only matching lines are kept.
exclude		Regexes. Matching lines are dropped.
tags		Extra key:value tags for this service.
multiline		Joins lines into one event.
status		Severity detection and overrides.

Paths and wildcards

Pattern	Matches
/var/log/app.log	one file
/var/log/myapp/*.log	.log files directly inside /var/log/myapp
/var/log/myapp/**/*.log	.log files in /var/log/myapp and all sub-folders
/var/log/myapp/app-*.log	app-2026-11-11.log, app-worker.log, …
/KDS_system/failure/*log	every file whose name ends in log
/srv/{api,worker}/logs/*.log	either folder
'C:\inetpub\logs\LogFiles\**\*.log'	Windows, recursive

• Paths must be absolute.
• New files that match are picked up automatically, within scan_interval (10 s by default).
• On Windows, put paths in single quotes.

exclude_paths

Each entry can be a full path pattern or just a file name pattern:

path: /var/log/myapp/*
exclude_paths:
  - "*.gz"                     # compressed rotations
  - "*.[0-9]"                  # app.log.1, app.log.2 …
  - /var/log/myapp/audit.log   # one specific file

Rotated files

With a wildcard such as *, rotated copies like app.log.1 or app.log.gz also match. Exclude them, or use a more specific pattern such as *.log, so you don't get duplicates or binary data.

Filter lines: include and exclude

Both options take a list of regular expressions that are matched against each line (or each joined multiline event).

1. If the line matches any exclude regex, it's dropped.
2. Otherwise, if include is set, the line is kept only if it matches at least one include regex.
3. Otherwise, the line is kept.

So exclude always wins over include.

# Only errors and warnings, but never health checks
include:
  - '(?i)\b(error|warn|warning|fatal)\b'
exclude:
  - '/health(z|check)?'
  - 'kube-probe'

Writing regexes

• Use single quotes so \d, \b and \s work as written.
• (?i) at the start makes a regex case-insensitive.
• | means "or": 'timeout|refused|reset'.
• A regex matches anywhere in the line unless you anchor it with ^ (start) or $ (end).
• The syntax is RE2 (Go). Look-ahead and look-behind ((?=…), (?!…)) aren't supported.

Filtered lines are counted as filtered by rules in logcore-agent status.

Multiline events

Stack traces and other multi-line messages should arrive as one log event. Set pattern to a regex that matches the first line of a new event; lines that don't match are appended to the previous event.

multiline:
  pattern: '^\d{4}-\d{2}-\d{2}'   # every event starts with 2026-11-11...
  max_lines: 500                  # an event is cut after this many lines
  timeout: 2s                     # an event is sent if no new line arrives within this time

This joins:

2026-11-11 10:42:01 ERROR payment failed
java.lang.IllegalStateException: card declined
    at com.shop.Payments.charge(Payments.java:88)
    at com.shop.Checkout.run(Checkout.java:41)
2026-11-11 10:42:02 INFO retrying

into two events.

Common start patterns:

Log format	pattern
2026-11-11 10:42:01 …	'^\d{4}-\d{2}-\d{2}'
[2026-11-11T10:42:01Z] …	'^\[\d{4}-'
Nov 11 10:42:01 … (syslog)	'^[A-Z][a-z]{2} +\d+ '
INFO …, ERROR …	`'^(TRACE
Python tracebacks after a dated line	'^\d{4}-\d{2}-\d{2}'
JSON lines {"…	'^\{'

Status

Each event gets a status of critical, error, warning, info or debug. The agent decides it in this order:

1. Overrides. The first overrides entry whose match regex matches sets the status.
2. Auto-detection (detect: auto, the default). The agent looks for a level keyword such as ERROR, warn or fatal in the first 256 characters. See the keyword table.
3. Default. default is used, which is info unless you change it.

status:
  detect: auto
  default: info
  overrides:
    - match: 'OutOfMemoryError|Too many open files'
      status: critical
    - match: ' 5\d\d '            # HTTP 5xx in an access log
      status: error
    - match: ' 4\d\d '
      status: warning

Use detect: none when level keywords in your messages are misleading, for example a log of "error pages served". In that case only overrides and default apply.

# A file that contains only failures
name: kds_failures
path: /KDS_system/failure/*log
status:
  detect: none
  default: error

Tags

Tags in a service file are added to every event from that service, on top of the host tags from logcore.yaml:

tags: ["team:payments", "app:checkout", "tier:1"]

Use key:value form so you can filter and facet by them in Logs.

File permissions (Linux)

On Linux the agent runs as the logcore-agent user, which can read /var/log (through the adm group) but not your application folders. If a service shows [ERROR] permission denied, give it read access:

sudo setfacl -R -m u:logcore-agent:rX /opt/myapp/logs      # existing files and folders
sudo setfacl -R -d -m u:logcore-agent:rX /opt/myapp/logs   # files created later
sudo -u logcore-agent head -n1 /opt/myapp/logs/app.log     # test

Parent folders need execute (x) permission too. As an alternative, reinstall with LOGCORE_RUN_AS_ROOT=true.

Notes

• Timestamp. Each event is stamped with the time the agent read it, which is normally within a second or two of when it was written.
• Encoding. Files should be UTF-8. A UTF-8 byte order mark is skipped, and invalid bytes are replaced.
• Long lines over 256 KB are split. See max_line_bytes.
• Inline services. Services can also be listed under a top-level services: key in logcore.yaml, but separate files are easier to manage.

See Service file examples for ready-to-use files.