> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Log Queries

> Log Query Language Syntax

*Last Updated: January 6, 2026*

The Salad Log Query Language aims to provide a powerful and flexible way to query and analyze logs generated by your
applications running on the Salad platform. It supports a variety of boolean operators, string patterns, and case
sensitivity constraints. It is used via the
[Query Log Entries endpoint](/reference/saladcloud-api/logs/query-log-entries) in the API.

## Basic Syntax

Each query is composed of one or more clauses, which can be combined using boolean operators. The basic structure of a
query is as follows:

```
field operator value
```

* `field`: The log field to query (e.g., `time`, `resource.labels.container_group_name`, `json_log.custom_field`).
* `operator`: The comparison operator to use (e.g., `=`, `!=`, `>`, `<`, `contains`).
* `value`: The value to compare against (e.g., a string, number, or date).

For example, the following query retrieves all logs with a severity of "error":

```
severity = "error"
```

You can also combine multiple clauses using boolean operators:

```
severity = "error" AND resource.labels.container_group_name = "my-container-group"
```

This query retrieves all error logs for a specific container group.

## Log Schema

Log events are JSON objects with the following structure:

```json theme={null}
{
  "time": "string iso8601",
  "receive_time": "string iso8601",
  "resource": {
    "type": "string enum",
    "labels": {
      // key-value pairs (string to string) specific to `type`
    }
  },
  "severity": "string enum",
  "severity_number": "integer",

  "trace_id": "string", // optional
  "span_id": "string", // optional
  "parent_span_id": "string", //optional

  // only one of `text_log` or `json_log`
  "text_log": "string",
  "json_log": {
    // key-value pairs (string to any valid JSON type) specific to log entry
  }
}
```

* Note that a log event will have ***EITHER*** a `text_log` ***OR*** a `json_log`, but not both. If your application
  emits a log that is valid JSON, it will be parsed and made available via `json_log`. Otherwise, the raw text will
  available in `text_log`.
* No operators are allowed to query on `json_log` directly, however you can query on any specific json fields within
  `json_log`, e.g. `json_log.my_field`.
* You can do full-text search independent of structured fields by querying a special `log` field. The `log` field only
  supports the `contains`, `!contains`, `contains~`, and `!contains~` operators. It searches across both `text_log` and
  `json_log` fields.
* The `time` field indicates the system time on the node where the log was emitted.
* The `receive_time` field indicates the time when the log was received.
* Any of these fields can be used in the query language.
* Time and Date values take the form `YYYY-MM-DDTHH:MM:SSZ`, and are expressed in UTC.

### Resource Types And Labels

You can query logs from three different resource types, indicated in the field `resource.type`:

* `container`: Logs from a running container instance. This includes all logs emitted to stdout and stderr within the
  container.
* `instance_controller`: System events that occur on the instance level, such as container start and stop events, probes
  passing and failing, etc.
* `deployment_controller`: System events that occur on the container group level, such as adjusting replica count, and
  starting and stopping container groups.

All of these types have the following labels:

* `project_name`: The name of your project in SaladCloud.
* `container_group_name`: The name of your container group in SaladCloud.

The `container` and `instance_controller` types have the following additional labels:

* `container_group_version`: The version of your container group when the log was emitted.
* `instance_id`: A unique ID for a specific instantiation of a container instance. This is independent from
  `machine_id`, because a single machine ID can have multiple instance IDs associated with it, if a container has
  recreated or restarted a number of times on the same machine. In such a situation, each "run" has its own
  `instance_id`.
* `machine_id`: The unique ID of the node running the container that created the log message.

## Operators

The following operators are supported in log queries:

* `=`: Equality (Case Sensitive)
* `=~`: Equality (Case Insensitive)
* `!=`: Inequality (Case Sensitive)
* `!=~`: Inequality (Case Insensitive)
* `>`: Greater than.
* `<`: Less than.
* `>=`: Greater than or equal to.
* `<=`: Less than or equal to.
* `contains`: String contains (Case Sensitive)
* `contains~`: String contains (Case Insensitive)
* `!contains`: String does not contain (Case Sensitive)
* `!contains~`: String does not contain (Case Insensitive)
* `startswith`: String starts-with (Case Sensitive)
* `startswith~`: String starts-with (Case Insensitive)
* `!startswith`: String does not start with (Case Sensitive)
* `!startswith~`: String does not start with (Case Insensitive)
* `endswith`: String ends-with (Case Sensitive)
* `endswith~`: String ends-with (Case Insensitive)
* `!endswith`: String does not end with (Case Sensitive)
* `!endswith~`: String does not end with (Case Insensitive)

## Combining Statements

Query statements can be combined with the following boolean operators:

* `and`: Logical AND
* `or`: Logical OR
* `not`: Logical NOT

Additionally, statements may be grouped together in parenthesis, like so:

```
resource.labels.container_group_name = "my-container-group" and
(severity = "error" or severity = "warning")
```

## Field Promotion in Structured Logs

If you emit structured logs (meaning logs that are valid JSON) with any of the following fields, it will be removed from
the `json_log` field and promoted to a top-level field in the log entry.

* `severity`
* `severity_number`
* `trace_id`
* `span_id`
* `parent_span_id`

Note that including a `time` or `receive_time`field in your structured log **WILL NOT** override the respective time
fields of the log entry.

## Troubleshooting Common Issues

* Ensure that quotes are properly escaped in your `.query` field.
* Ensure that times are specified in UTC and follow the ISO 8601 format, i.e. `YYYY-MM-DDTHH:MM:SSZ`
* Ensure that times are within the retention period of your logs.
* Ensure that times are in the past, i.e. no future times.

## Examples

### Find Logs From All Containers in a Specific Container Group

```plaintext theme={null}
resource.type = "container" and
resource.labels.project_name = "default" and
resource.labels.container_group_name = "my-cg"
```

```shell theme={null}
curl --request POST \
  --url https://api.salad.com/api/public/organizations/$organization_name/log-entries \
  --header 'Content-Type: application/json' \
  --header "Salad-Api-Key: $salad_api_key" \
  --data '{
  "sort_order": "desc",
  "end_time": "2025-08-28T05:54:42Z",
  "start_time": "2025-08-28T01:44:42Z",
  "page_size": 20,
  "query": "resource.type = \"container\" and resource.labels.project_name = \"default\" and resource.labels.container_group_name = \"my-cg\""
}'
```

### Search Logs By severity

```plaintext theme={null}
severity >= "warning"
```

```shell theme={null}
curl --request POST \
  --url https://api.salad.com/api/public/organizations/$organization_name/log-entries \
  --header 'Content-Type: application/json' \
  --header "Salad-Api-Key: $salad_api_key" \
  --data '{
  "sort_order": "desc",
  "end_time": "2025-08-28T05:54:42Z",
  "start_time": "2025-08-28T01:44:42Z",
  "page_size": 20,
  "query": "severity >= \"warning\""
}'
```

### Search Text in Unstructured Logs

```plaintext theme={null}
text_log contains "rejected"
```

```shell theme={null}
curl --request POST \
  --url https://api.salad.com/api/public/organizations/$organization_name/log-entries \
  --header 'Content-Type: application/json' \
  --header "Salad-Api-Key: $salad_api_key" \
  --data '{
  "sort_order": "desc",
  "end_time": "2025-08-28T05:54:42Z",
  "start_time": "2025-08-28T01:44:42Z",
  "page_size": 20,
  "query": "text_log contains \"rejected\""
}'
```

### Search Custom Fields in Structured Logs

```plaintext theme={null}
json_log.custom_field = "value"
```

```shell theme={null}
curl --request POST \
  --url https://api.salad.com/api/public/organizations/$organization_name/log-entries \
  --header 'Content-Type: application/json' \
  --header "Salad-Api-Key: $salad_api_key" \
  --data '{
  "sort_order": "desc",
  "end_time": "2025-08-28T05:54:42Z",
  "start_time": "2025-08-28T01:44:42Z",
  "page_size": 20,
  "query": "json_log.custom_field = \"value\""
}'
```