Error Event Grouper

Overview

You bind our roles to your log's own keys, say which roles form the group and how each one is normalised, and we return the distinct error classes with their counts and line numbers. The six normalisations run in one published order whatever order you list them in, so two people expressing the same intent get the same key. Nothing here is fingerprinting, fuzzy matching or a regular expression: you can predict every group from the documentation. No raw event comes back, only the normalised parts of the key and the lines to look at.

Grouping errors by hand means writing regular expressions against your own logs and rediscovering that request ids, hex object ids and path segments are what keep identical failures looking distinct.

When to use it

Scope

Non-goals

• Does not fingerprint, cluster fuzzily or infer that two messages are alike
• Does not accept a regular expression, a template or any field expression
• Does not parse stack traces, which code.parse_stacktrace answers
• Does not echo any raw log line, message or record back to you
• Does not store, forward or scrape anything, and reads no clock

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

File limits

Constraints this skill applies to your input and generated files. The “Limited by” column shows the static source of each cap; none of these can be raised by upgrading your plan.

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"observability.extract_error_events","input":{"records":[{"lvl":"error","msg":"boom"}],"fieldBindings":{"LEVEL":"lvl","MESSAGE":"msg"},"groupingRules":{"groupBy":["MESSAGE"]}}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("observability.extract_error_events", {"groupingRules":{"groupBy":["MESSAGE"],"normalise":{"MESSAGE":["MASK_DIGITS","CASE_FOLD"]}},"logs":"{\"lvl\":\"error\",\"msg\":\"order 12 failed\"}\n{\"lvl\":\"error\",\"msg\":\"order 3456 failed\"}\n{\"lvl\":\"info\",\"msg\":\"order 7 placed\"}\n","format":"JSON_LINES","fieldBindings":{"MESSAGE":"msg","LEVEL":"lvl"}});

Errors

Other limits

Limitations

• Does not fingerprint, cluster fuzzily or infer that two messages are alike
• Does not accept a regular expression, a template or any field expression
• Does not parse stack traces, which code.parse_stacktrace answers
• Does not echo any raw log line, message or record back to you
• Does not store, forward or scrape anything, and reads no clock
• Grouping messages that share no exact field after normalisation
• Extracting frames from a stack trace

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "observability.extract_error_events",
  "input": {
    "groupingRules": {
      "groupBy": [
        "MESSAGE"
      ],
      "normalise": {
        "MESSAGE": [
          "MASK_DIGITS",
          "CASE_FOLD"
        ]
      }
    },
    "logs": "{\"lvl\":\"error\",\"msg\":\"order 12 failed\"}\n{\"lvl\":\"error\",\"msg\":\"order 3456 failed\"}\n{\"lvl\":\"info\",\"msg\":\"order 7 placed\"}\n",
    "format": "JSON_LINES",
    "fieldBindings": {
      "MESSAGE": "msg",
      "LEVEL": "lvl"
    }
  }
}

Examples

{
  "groupingRules": {
    "groupBy": [
      "MESSAGE"
    ],
    "normalise": {
      "MESSAGE": [
        "MASK_DIGITS",
        "CASE_FOLD"
      ]
    }
  },
  "logs": "{\"lvl\":\"error\",\"msg\":\"order 12 failed\"}\n{\"lvl\":\"error\",\"msg\":\"order 3456 failed\"}\n{\"lvl\":\"info\",\"msg\":\"order 7 placed\"}\n",
  "format": "JSON_LINES",
  "fieldBindings": {
    "MESSAGE": "msg",
    "LEVEL": "lvl"
  }
}

{
  "summary": {
    "selectedCount": 2,
    "examinedCount": 3,
    "groupCount": 1,
    "skippedUnselectedCount": 1,
    "parseErrorCount": 0,
    "truncated": false
  },
  "groups": [
    {
      "groupKey": "c6a54f1242e06a42",
      "keyParts": [
        {
          "value": "order # failed",
          "present": true,
          "role": "MESSAGE"
        }
      ],
      "count": 2,
      "firstSeenLine": 1,
      "lastSeenLine": 2,
      "keyTruncated": false
    }
  ]
}

{
  "records": [
    {
      "lvl": "error",
      "svc": ""
    },
    {
      "lvl": "error"
    }
  ],
  "fieldBindings": {
    "LEVEL": "lvl",
    "SERVICE": "svc"
  },
  "groupingRules": {
    "groupBy": [
      "SERVICE"
    ]
  }
}

{
  "summary": {
    "selectedCount": 2,
    "examinedCount": 2,
    "groupCount": 2,
    "skippedUnselectedCount": 0,
    "parseErrorCount": 0,
    "truncated": false
  },
  "groups": [
    {
      "groupKey": "75e31cdf1ce3b03b",
      "keyParts": [
        {
          "value": "",
          "present": true,
          "role": "SERVICE"
        }
      ],
      "count": 1,
      "firstSeenLine": 1,
      "lastSeenLine": 1,
      "keyTruncated": false
    },
    {
      "groupKey": "0788d0f936d5054e",
      "keyParts": [
        {
          "value": "",
          "present": false,
          "role": "SERVICE"
        }
      ],
      "count": 1,
      "firstSeenLine": 2,
      "lastSeenLine": 2,
      "keyTruncated": false
    }
  ]
}

Recommended use cases

• Find the handful of distinct error classes hiding behind ten thousand lines
• Collapse per-request ids out of error messages so the real classes stand out

Avoid for

• Grouping messages that share no exact field after normalisation
• Extracting frames from a stack trace

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags