Remap JSON attribute fields to top-level log event fields

The remapper transform moves or copies log event attributes to top-level log event fields, such as message or eventTimestamp, or to tags. You can also rename attributes by moving a value from one attribute path to another. See The remapper transform rename rules.

When you use the Grepr UI to create a pipeline, a remapper that transforms a default set of commonly used fields is automatically added to the pipeline, but you can modify which fields are transformed based on your requirements.

Example remapper transformation

For example, this event:

{
  "id": "ABCDEF",
  "eventTimestamp": 1765481731051,
  "message": "",
  "severity": "",
  "tags": {},
  "attributes": {
    "syslog": {
      "severity": "10",
      "appname": "test name"
    },
    "status": "5",
    "msg": "message 1",
    "timestamp": {
      "ms_since_epoch": 1765481730000
    },
    "eventTime": " "
  }
}

Would be transformed using the default configuration to:

{
  "id": "ABCDEF",
  "eventTimestamp": 1765481731051,
  "message": "message 1",
  "severity": "5",
  "tags": {
    "service": "test name"
  },
  "attributes": {
    "syslog": {
      "severity": "10",
      "appname": "test name"
    },
    "status": "5",
    "timestamp": {
      "ms_since_epoch": 9001
    },
    "eventTime": " ",
    "greprMeta": {
      "messageAttributePath": "msg"
    }
  }
}

• severity uses status: "5" instead of syslog.severity: "10" because status has a higher priority in the default configuration.
• tags.service uses syslog.appname: "test name".
• The attribute msg is removed because it’s remapped to the top-level message field and the message field has preserve source disabled by default.
  • The greprMeta.messageAttributePath attribute is added to indicate which attribute was used for the remapped message field.
  • If the message attribute is a nested field, for example, log.msg, only the msg field is removed. The parent log object remains, even if it is empty.
• Other remapped attributes like status and syslog.appname remain in their original locations because their corresponding fields have preserve source enabled by default.
• timestamp: {} and eventTime: " " are not used because they do not contain a valid timestamp value.

The remapper transform default configuration

The following is the default remapper configuration. The Transformed attribute or tag column shows the field name in the transformed event after the input event is processed. The Preserve source column indicates whether the source attribute is kept in the original location after its value is copied to the target field, and Default paths searched are where the remapper looks in the input event for fields to transform.

You can toggle the Preserve source setting for each field in the pipelines UI. When preserve source is enabled, the source attribute remains in its original location after the value is copied to the target field. When disabled, the source attribute is removed after remapping. For example, the message field has preserve source disabled by default, so the original msg attribute is deleted after being copied to the top-level message field.

Tag mappings also support the preserve source option. You can configure whether the source attribute is kept or removed after its value is copied to a tag.

For the full list of default configuration settings, see the LogAttributesRemapper specification.

The remapper transform rename rules

To move or copy an attribute value from one path to another path, use a rename rule. Rename rules move an attribute value from one path to another in the same log event. Each rule has a Preserve source setting that controls whether the source attribute is kept or removed after its value is copied to the target path. If the target path already exists, its value is overwritten.

To add rename rules in the pipelines UI, click JSON Parser in the navigation menu, click Edit next to Attribute Remapper, then select the Rename Rules tab. Rules can be reordered by dragging them, and they are applied in order from top to bottom.

Example rename rule

Given the following attributes:

{
  "attributes": {
    "request": {
      "method": "POST",
      "path": "/api/users"
    }
  }
}

A rename rule with source request.method and target http_method produces:

{
  "attributes": {
    "request": {
      "path": "/api/users"
    },
    "http_method": "POST"
  }
}

The source field request.method is removed, while sibling fields like request.path are preserved.

Preserving the source attribute

When Preserve source is disabled on a rename rule, the source attribute is removed after its value is copied to the target. To keep the source attribute in its original location, enable the Preserve source checkbox on the rule. This copies the value to the target path without removing the original.

Using the same example above, with Preserve source enabled, the result would be:

{
  "attributes": {
    "request": {
      "method": "POST",
      "path": "/api/users"
    },
    "http_method": "POST"
  }
}

The value is copied to http_method, but request.method remains in its original location.

Conditional rename rules

Each rename rule can include an optional filter query. When a filter is set, the rule only applies to log events that match the query. This allows you to define multiple rules for the same source attribute with different filters, so each rule targets a different subset of events.

For example, you could configure two rules for the same source origin:

• origin → cloud.provider when the filter matches env:production
• origin → debug.origin when the filter matches env:staging

Because the filters are mutually exclusive, only one rule applies per event.

Rule ordering

Rename rules are applied sequentially in the order they appear. If two rules share the same source attribute, the first matching rule removes the source value. Subsequent rules for the same source will not find a value unless their filters prevent the earlier rule from applying.

See the AttributeRemappingRule specification.