PostHog / PostHog/posthog

docs(error-tracking): $issue_name and $issue_description are undocumented, so custom issue naming looks missing

Open
#84,533 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug feature/error-tracking team/docs-wizard team/error-tracking
Dominant language
Python
Stars
39.9k
Forks
3.4k
Avg merge
6h 51m
Merged PRs (30d)
232

Description

Problem

A user who groups exceptions with a custom $exception_fingerprint gets an issue named after whichever event arrived first, and asks us to add a property that sets the issue name. That property already exists. It is called $issue_name, with $issue_description alongside it, and it appears in no documentation, so the capability reads as missing.

IssueLinker::fetch_or_create_issue in rust/cymbal/src/modes/processing/stages/linking/issue.rs takes both values from the event and falls back to the exception:

let name = input
    .proposed_issue_name()
    .map(str::to_string)
    .unwrap_or_else(|| input.exception_list()[0].exception_type.clone());

let description = input
    .proposed_issue_description()
    .map(str::to_string)
    .unwrap_or_else(|| input.exception_list()[0].exception_message.clone());

proposed_issue_name carries the $issue_name property, and rust/cymbal/src/modes/processing/types/exception_event.rs truncates both to 255 bytes. resolve_issue applies the name and the description only on the insert path, so the first event that creates the issue sets them.

The documentation does not carry either property. contents/docs/error-tracking/capture.mdx and contents/docs/error-tracking/issues-and-exceptions.mdx both list $exception_list, $exception_fingerprint, $exception_level and $exception_steps, and neither lists $issue_name or $issue_description. contents/docs/error-tracking/grouping-issues.mdx and contents/docs/error-tracking/fingerprints.mdx explain a client-side fingerprint, and neither says what names the resulting issue.

Behaviour to document:

  1. $issue_name sets the issue name. $issue_description sets the issue description.
  2. Both truncate at 255 bytes.
  3. The first event wins. A later event does not rename an existing issue.
  4. Without them the name is exception_list[0].type and the description is exception_list[0].value. A deliberately merged group therefore takes the type and message of whichever event arrived first.

Proposed fix

  1. Add both properties to the property tables in contents/docs/error-tracking/capture.mdx and contents/docs/error-tracking/issues-and-exceptions.mdx, with the 255-byte limit and the first-event-wins rule.
  2. State in contents/docs/error-tracking/grouping-issues.mdx and contents/docs/error-tracking/fingerprints.mdx that a custom fingerprint keeps the first event's exception type as the issue name unless the event sets $issue_name.
  3. Decide whether to accept $exception_issue_name and $exception_issue_description as aliases. Every other error-tracking ingest property carries the $exception_ prefix, and that inconsistency is why a user does not find this property today.

Acceptance criteria

  1. A user who searches the documentation for custom issue naming finds $issue_name.
  2. The exception property tables list both properties, their truncation limit, and the first-event-wins rule.
  3. The custom grouping documentation states what names a merged issue.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the property tables in contents/docs/error-tracking/capture.mdx and contents/docs/error-tracking/issues-and-exceptions.mdx, then read grouping-issues.mdx and fingerprints.mdx alongside rust/cymbal/src/modes/processing/stages/linking/issue.rs and exception_event.rs. Document both properties, their 255-byte limit, first-event-wins behavior, fallbacks, and custom-fingerprint naming; also resolve the proposed alias question. Done when the acceptance criteria are covered in all four documentation files.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, observability
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.