By default, the OpsRamp Kubernetes 2.0 Agent collects logs from every pod across every namespace in your cluster, with no configuration required. This page covers how to customize that default behavior, turning pod log collection on or off, tagging logs with custom labels, and scoping collection to specific namespaces.

All settings on this page are configured in the opsramp-logs-user-config ConfigMap, under the pods section.

Prerequisites

  • Log Management is enabled for your client.
  • The OpsRamp Kubernetes 2.0 Agent is installed and running.

The default configuration

After installation, the agent ships with a default opsramp-logs-user-config ConfigMap that doesn’t apply any customization, it simply gives you a starting point to edit.

To view it:

kubectl get configmap opsramp-logs-user-config -n <agent-installed-namespace>

You’ll see something like this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: "opsramp-logs-user-config"
  labels:
    app: "opsramp-logs-user-config"
  namespace: opsramp-agent
data:
  logsConfig.yaml: |
    pods:
      enable: true
      additional_labels:
      namespaces:
        include:
        is_include_regex: false
        exclude:
        is_exclude_regex: false
      log_level: "Unspecified"
      masking:
        - attribute_type: ""
          attribute_key: ""
          text: ""
          placeholder: ""
          mode: ""

To make any change described below, edit this ConfigMap directly:

kubectl edit configmap opsramp-logs-user-config -n <agent-installed-namespace>

The agent automatically detects changes to this ConfigMap and restarts the underlying log collector to apply them. You don’t need to restart the agent manually.

Turning pod log collection on or off

To stop collecting pod logs entirely, set enable to false under pods:

pods:
  enable: false

Set it back to true at any time to resume collection.

Adding custom labels to every log record

Use additional_labels to attach custom key-value metadata to every pod log record the agent collects. This is useful for tagging logs with context like environment or application name, which you can then filter on in the OpsRamp Logs UI.

pods:
  enable: true
  additional_labels:
    app: nginx
    env: staging

In this example, every log record collected will include app: nginx and env: staging as attributes.

Filtering by namespace

By default, the agent collects pod logs from all namespaces. If you only want logs from specific namespaces or want to exclude a few noisy ones, configure include and exclude rules under namespaces.

pods:
  enable: true
  namespaces:
    include:
      - ^monitoring
    is_include_regex: true
    exclude:
      - monitoring-test
    is_exclude_regex: false

How include and exclude work together:

IncludeExcludeResult
Not setNot setCollects logs from all namespaces.
Some filterNot setCollects logs only from namespaces that match the include filter.
Not setSome filterCollects logs from all namespaces except those that match the exclude filter.
Some filterSome filterCollects logs from namespaces that match the include filter, excluding any that also match the exclude filter.

Rules for include and exclude values:

  • Both fields accept either an exact namespace name or a regex pattern.
  • If you use a regex pattern, set the corresponding flag (is_include_regex or is_exclude_regex) to true.
  • If you use a plain namespace name (not a regex), set the corresponding flag to false.

Common examples:

GoalConfiguration
Collect logs only from the agent namespace.include: [agent], is_include_regex: false
Collect logs from all namespaces that start with test.include: [^test], is_include_regex: true
Collect logs from all namespaces except kube-system.exclude: [kube-system], is_exclude_regex: false
Collect logs from all namespaces except those ending with system.exclude: [system$], is_exclude_regex: true
Collect logs from namespaces that start with test or kube.include: ["^test\|^kube"], is_include_regex: true
Collect logs from namespaces that start with test or kube, but exclude testing and kube-system.include: ["^test\|^kube"], is_include_regex: true
exclude: [testing, kube-system], is_exclude_regex: false
Collect logs from namespaces ending with agent, excluding namespaces that start with opsramp.include: [agent$], is_include_regex: true
exclude: [^opsramp], is_exclude_regex: true

Performance tuning for large environments

Two settings let you control how much log history the agent scans and tracks. This is useful if you are managing clusters with a very high volume of log files.

Controlling how far back logs are read (max_time)

max_time sets how far back in time the agent looks when reading log files. The default is 2 hours, meaning only files modified within the last 2 hours are processed. This keeps overhead low by skipping stale files.

pods:
  enable: true
  max_time: 10h

Format note: max_time only accepts durations in seconds, minutes, or hours (e.g., 60s, 30m, 2h). If you need to express days, convert to hours first (e.g., 3 days = 72h).

Controlling how many files are tracked (top_n)

top_n sets the maximum number of log files the agent tracks for file ordering. The default is 500 files, evaluated within the max_time window.

pods:
  enable: true
  max_time: 10h
  top_n: 700

With this example, the agent tracks up to 700 files that were modified within the last 10 hours.

Advanced settings

Pod log collection has a few more advanced capabilities, each covered on its own page: