Parse your log data

Your log data can be formatted differently depending on which service generates that data. Some data is structured, such as valid JSON. Other data might be somewhat structured, or not have any structure at all. In these instances, you can create parsers to create structured logs from plain text logs, and parse individual fields to extract meaningful data without changing your instrumentation. For example, if your instrumentation emits unstructured plain-text logs, create a plain text parser to provide structure by separating the individual fields. If your logs contain JSON or key/value pairs buried contained in a single string field, create a field parser to extract the values. The extracted fields can then be queried in Logs Explorer and used in aggregations and transformations.

View parsers

Select from the following methods to view and order available parsers. Parsers display in match order.

Web
Chronoctl
Terraform
API

To view parsers:

In the navigation menu, click Go to Admin and then select Control > Logs Parsing and Mapping. All parsers display, including plain-text and field parsers.
To view the code definition for all configured parsers, click the Code Config tab.

To use Chronoctl to return all parsers, use the chronoctl log-ingest-config read command:

chronoctl log-ingest-config read

To complete this action with the Chronosphere API, use the ReadLogIngestConfig endpoint.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Create parsers

Parsers operate on both plain-text logs and individual fields. All configured parsers are included in a single definition, and evaluated in match order. Observability Platform applies the first parser in the definition that matches a log, and ignores any subsequent parsers. Although you can define parsers in the Observability Platform web interface, you must use the Code Config tool to apply the definition.

Create plain-text parsers

Plain text parsers run against all ingested logs with the plaintext mimetype, and apply parsing logic to modify the original record. These parsers affect the entire log. Use field parsers to operate on individual fields within a log. Select either a regular expression or a key/value matching pattern to parse logs. When using a key/value pattern, you can extract any number of key value pairs from a plain text log. Plain text parsers also have an option to keep the original log after applying parsing logic. Plain text parsers apply only when the media type is set to plaintext for logs. Regular expressions for the matching type use RE2 syntax and named capture groups. Each named capture group becomes the key name in the structured log. Observability Platform requires at least one named capture group in the regular expression. Use one of the following methods to create plain text parsers.

Web
Chronoctl
Terraform
API

Define the plain text parser definition in Observability Platform, and then use the Code Config tool to apply the definition.

In the navigation menu, click Go to Admin and then select Control > Logs Parsing and Mapping.
In the Plaintext Parsers section, click Create plaintext parser.
Enter a name for the parser.
Select the matching type for the parser:
- REGEX: Use a regular expression to match logs. In the Template field, select the regular expression template to apply to your logs. Use a predefined template such as Nginx, or specify a Custom template.
- Key/value: Use a specified pattern to separate key/value pairs in log data. Enter the following values:
  - Pair separator: Specifies the character used to split matching pairs into its key and value. For example, a colon (:) if your data is in the format key: value.
  - Delimiter: Specifies the character used to split the input log data into key/value pairs. For example, a comma (,) if your data is in the format key: value, key: value.
  - Trim set: Identifies the leading and trailing characters to trim from the key/value pairs. For example, a space (" ") between key/value pairs if your data is in the format key: value, key: value.
If you want to keep the original log after parsing, select the corresponding checkbox.
Click Save to save the parser definition.
On the Logs Parsing and Mapping page, click View code config.
In the Code Config tab, use the Code Config tool to apply the definition.

To use Chronoctl to create plain text parsers, use the chronoctl log-ingest-config create command:

chronoctl log-ingest-config create

Run the following command to generate a sample parser configuration you can use as a template:
```
chronoctl log-ingest-config scaffold
```
In the template, kind: LogIngestConfig defines an individual parser configuration.
Use the plaintext_parsers object to define the plain text parser to run on your log data.
With a completed definition, submit it with:
```
chronoctl log-ingest-config create -f FILE_NAME
```
Replace FILE_NAME with the name of the YAML definition file you want to use.

When you run terraform plan to generate an execution plan, Chronosphere automatically tests configurations that include notification policies by submitting them as dry runs. For details, see the Terraform provider documentation.

To create a plain text parser with Terraform:

Create a Terraform resource with the chronosphere_log_ingest_config resource type, followed by a resource name.
Use the plaintext_parser object to define the plain text parser to run on your log data.
Add the definition to a Terraform file.
Run this command to create the resource:
```
terraform apply
```

To complete this action with the Chronosphere API, use the CreateLogIngestConfig endpoint.Use the plaintext_parsers object to define the plain text parser to run against your log data.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Create field parsers

Field parsers operate on an individual field within a log, and run on all ingested logs, including JSON and plain text logs. Field parsers run after plain text parsers. When defining a field parser, choose which matching pattern to apply and specify the destination of the parsed field.

Web
Chronoctl
Terraform
API

Define the field parser definition in Observability Platform, and then use the Code Config tool to apply the definition.

In the navigation menu, click Go to Admin and then select Control > Logs Parsing and Mapping.
In the Field Parsers section, click Create field parser.
Enter a source field for the parser to operate on, such as message.
Enter a destination for the parsed data, which can be one of these locations:
- Use the same field name, which overwrites the existing field data with the parsed data.
- Specify a new field name to contain the parsed data.
- Leave the destination field empty, which populates the parsed data to the top level of your logs.
Select the matching type for the parser.
- JSON matches on valid JSON logs.
- REGEX uses a regular expression to match logs. In the Template field, select the regular expression template to apply to your logs. Use a predefined template such as Nginx, or specify a Custom template.
- Key/value uses a specified pattern to separate key/value pairs in log data. Enter the following values:
  - Pair separator is the character used to split matching pairs into its key and value. For example, a colon (:) if your data is in the format key:value.
  - Delimiter is the character used to split the input log data into key/value pairs. For example, a comma (,) if your data is in the format key: value, key: value.
  - Trim set identifies the leading and trailing characters to trim from the key/value pairs. For example, a space (" ") between key/value pairs if your data is in the format key: value, key: value.
Click Save to save the parser definition.
On the Logs Parsing and Mapping page, click View code config.
In the Code Config tab, use the Code Config tool to apply the definition.

To use Chronoctl to create field parsers, use the chronoctl log-ingest-config create command:

chronoctl log-ingest-config create

Run the following command to generate a sample parser configuration you can use as a template:
```
chronoctl log-ingest-config scaffold
```
In the template, kind: LogIngestConfig defines an individual parser configuration.
Use the field_parsers object to define the plain text parser to run on your log data.
With a completed definition, submit it with:
```
chronoctl log-ingest-config create -f FILE_NAME
```
Replace FILE_NAME with the name of the YAML definition file you want to use.

To create a plain text parser with Terraform:

Create a Terraform resource with the chronosphere_log_ingest_config resource type, followed by a resource name.
Use the field_parser object to define the field parser to run on your log data.
Add the definition to a Terraform file.
Run this command to create the resource:
```
terraform apply
```

To complete this action with the Chronosphere API, use the CreateLogIngestConfig endpoint.Use the field_parsers object to define the field parser to run against your log data.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Edit parsers

When creating or editing a parser, you can use the Code Config tool to view code representations of a parser. The displayed code also responds to changes you make in the Visual editor tab. Select from the following methods to edit parsers.

Web
Chronoctl
Terraform
API

In the navigation menu, click Go to Admin and then select Control > Logs Parsing and Mapping.
In the row of the parser you want to edit, click the three vertical dots icon and then click Edit parser.
In the Edit parser drawer, make changes to your parser, and then click Save.

Observability Platform saves changes to your parser.

To update parsers with Chronoctl, use the log-ingest-config update command:

chronoctl log-ingest-config update

Update the parser definition file.
Run the following command to submit the changes:
```
chronoctl log-ingest-config update -f FILE_NAME.yaml
```
Replace FILE_NAME with the name of the YAML definition file you want to use.

Users can modify Terraform-managed resources only by using Terraform. Learn more.

To edit parsers using Terraform:

Create or edit a Terraform file that updates the resource’s existing properties.
Run this command to apply the changes:
```
terraform apply
```

You can also use the Code Config tool to view the parser’s Terraform representation.

To complete this action with the Chronosphere API, use the UpdateLogIngestConfig endpoint.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Delete parsers

Select from the following methods to delete parsers.

Web
Chronoctl
Terraform
API

In the navigation menu, click Go to Admin and then select Control > Logs Parsing and Mapping.
In the row of the parser you want to edit, click the three vertical dots icon and then click Delete parser.

Observability Platform deletes your parser.

To delete a parser with Chronoctl, use the chronoctl log-ingest-config delete command:

chronoctl log-ingest-config delete

Users can modify Terraform-managed resources only by using Terraform. Learn more.

To delete a resource that’s managed by Terraform:

Edit your Terraform configuration file to remove the pre-existing resource definition.
Run this command to remove the resource from Observability Platform:
```
terraform apply
```

To complete this action with the Chronosphere API, use the DeleteLogIngestConfig endpoint.Because the Chronosphere API requires authentication, include an API token with your curl request, as shown in the following example. For more details, see Create an API token.

export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"

Replace the following:

TOKEN: Your API token.
INSTANCE: The subdomain name for your organization’s Observability Platform instance.
METHOD: The HTTP method to use with the request, such as GET or POST.
ENDPOINT_PATH: The specific endpoint you want to access.

Examples

The following example shows how to apply both plain text and field parsers to create structured output from an unstructured log record. Consider the following input log data. The record is a single string that contains multiple key/value pairs in a single message field. In this state, querying the data is difficult, and you can’t complete aggregations or transformations.

2025-09-22 09:15:45.101 2025/09/22 13:15:45 [info] 34567#34567: *9876543210 a new
user session was started, client: 203.0.113.55, service: app.example.net, activity:
"GET /data/dashboard/overview?appVersion=1.2.3 HTTP/1.1", host: "app.example.net",
source: "https://app.example.net/home"

By applying a plain text parser and a field parser, you can separate the fixed fields and extract the key/value pairs into a new field that you can operate on in Logs Explorer. First, create a plain text parser that uses a regular expression to extract the key/value pairs. Next, add a field parser to parse out the values. The following Terraform definition includes both parsers and their definitions:

resource "chronosphere_log_ingest_config" "log_ingest_config" {

  plain text_parser {
    name = "metadata"
    mode = "ENABLED"

    parser {
      parser_type = "REGEX"

      regex_parser {
        regex = "^(?P<timestamp>\\S+ \\S+)\\s+(?P<log_time>\\S+ \\S+) \\[(?P<log_level>\\w+)\\] (?P<pid>\\d+)#(?P<tid>\\d+): \\*(?P<connection_id>\\d+) (?P<message>.*?), (?P<metadata>.+)$"
      }
    }
  }

  field_parser {
    destination {
      selector = "metadata"
    }

    mode = "ENABLED"

    parser {
      parser_type = "KEY_VALUE"

      key_value_parser {
        delimiter      = ","
        pair_separator = ":"
        trim_set       = " "
      }
    }

    source {
      selector = "metadata"
    }
  }
}

After applying both parsers, the generated data is output to a new metadata field, and is structured as shown in the following example. The new field includes key/value pairs that can be queried in Logs Explorer and used in aggregations and transformations.

{
      "timestamp": "2025-08-22 13:36:18.648",
      "log_time": "2025/08/22 17:36:18",
      "log_level": "info",
      "pid": "34567",
      "tid": "34567",
      "connection_id": "9876543210",
      "message": "a new user session was started",
      "metadata": {
        "client": " 203.0.113.55",
        "service": " app.example.net",
        "activity": " \"GET /data/dashboard/overview?appVersion=1.2.3\"",
        "host": " \"app.example.net\"",
        "source": " \"https://app.example.net/home\""
      }
    }

Observability Platform

Telemetry Pipeline

Tools

More information

View parsers

Create parsers

Create plain-text parsers

Create field parsers

Edit parsers

Delete parsers

Examples

Observability Platform

Telemetry Pipeline

Tools

More information

​View parsers

​Create parsers

​Create plain-text parsers

​Create field parsers

​Edit parsers

​Delete parsers

​Examples

View parsers

Create parsers

Create plain-text parsers

Create field parsers

Edit parsers

Delete parsers

Examples