Logs grouping

Grouping rules let you change how Uptrace groups logs and exceptions together. Each rule is a Grok-style pattern: literal words plus typed placeholders that extract variable parts (numbers, IPs, identifiers, etc.) and feed them into the grouping fingerprint.

For example, you can configure Uptrace to create a separate error group for each unknown PostgreSQL column:

# Error messages
ERROR: column "event.created_at" does not exist (SQLSTATE=42703)
ERROR: column "updated_at" does not exist (SQLSTATE=42703)
ERROR: column "name" does not exist (SQLSTATE=42703)

# Pattern
%{LOG_LEVEL:log_severity} column %{QUOTED:#column} does not exist %{ATTR:sqlstate}

Patterns

A pattern is a sequence of matchers separated by whitespace. Each matcher is either a literal word or a typed placeholder.

Literals

Plain words match tokens exactly:

error connecting to database

Typed placeholders

Typed placeholders use Grok syntax %{TYPE} to match variable tokens by type:

%{NUMBER}
%{IP}
%{LOG_LEVEL}

Capture name

Add a capture name after a colon to extract the matched value into an attribute:

%{NUMBER:status_code}
%{IP:remote_addr}

Prefix the capture name with # to also include the matched value in the grouping fingerprint hash. This is how you create a separate group per unique value:

%{IDENT:#function_name}

Without a capture name, use the fingerprint option instead:

%{IDENT,fingerprint}

Primary constraint

The parenthesized argument %{TYPE(arg)} constrains which tokens match. Its meaning depends on the type:

• Value constraint (most types): match only tokens with this exact value.
  text

  %{LOG_LEVEL(ERROR)}
  %{LOG_LEVEL(ERROR):level}
  

• Key constraint (ATTR): match only key=value tokens whose key equals the argument. The key auto-captures, so %{ATTR(status)} is equivalent to %{ATTR(status):status}. Use _ to suppress auto-capture.
  text

  %{ATTR(status)}
  %{ATTR(user_id):var}
  %{ATTR(status):_}
  

Options

Options are comma-separated key=value pairs after the capture name:

%{NUMBER:duration,unit=seconds}

Optional matchers

Append ? to make a matcher optional — the pattern still matches if the token is absent:

error code %{NUMBER:code}? occurred

This matches both error code 500 occurred and error code occurred.

Groups and alternatives

Parentheses define a group of alternatives separated by |:

(%{LOG_LEVEL:level}|%{WORD:level}) %{WORD:msg}

Groups themselves can be optional:

(%{LOG_LEVEL})?

REST

%{REST} matches and discards all remaining tokens — use it to ignore trailing content:

%{IDENT:function} failed %{REST}

Available types

Some types are virtual — they expand to several concrete types.

Text

Numeric

Network

Temporal

Structured

System

Type aliases

For compatibility with existing Grok corpora, several types have alternative names:

Fingerprints

Uptrace groups similar logs and exceptions by hashing certain parts of the message. By default it only hashes literal words; use # (or the fingerprint option) to include captured values in the hash.

For example:

unknown column: %{WORD:#column}

The pattern above creates a separate group for each column, which is useful for alerting:

# Group 1
unknown column: foo
unknown column: foo

# Group 2
unknown column: bar
unknown column: bar

You can also set the grouping.fingerprint attribute when creating logs and exceptions, which overrides the automatically derived fingerprint:

span := trace.SpanFromContext(ctx)

span.AddEvent("exception", trace.WithAttributes(
    attribute.String("exception.type", "*exec.ExitError"),
    attribute.String("exception.message", "exit status 1"),
    attribute.String("grouping.fingerprint", "exec.ExitError"),
))

Examples

Go-style error messages:

# Messages
strconv.ParseInt failed
SendEmail failed
mypkg.MyFunc failed

# Pattern
%{IDENT:#code_function} failed

PostgreSQL unknown column errors:

# Error messages
ERROR: column "event.created_at" does not exist (SQLSTATE=42703)
ERROR: column "updated_at" does not exist (SQLSTATE=42703)
ERROR: column "name" does not exist (SQLSTATE=42703)

# Pattern
%{LOG_LEVEL:log_severity} column %{QUOTED:#column} does not exist %{ATTR:sqlstate}

A single grouping rule may declare multiple patterns — any of them matching is enough:

can't find item %{NUMBER:item_id}
can not find item %{NUMBER:item_id}
%{NUMBER:item_id} not found

Conclusion

Grouping rules work best with structured logs and are not a replacement for the log parsers provided by OpenTelemetry Logs and Vector.