docs(error-tracking): $issue_name and $issue_description are undocumented, so custom issue naming looks missing
Nobody has claimed this yet.
- 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:
$issue_namesets the issue name.$issue_descriptionsets the issue description.- Both truncate at 255 bytes.
- The first event wins. A later event does not rename an existing issue.
- Without them the name is
exception_list[0].typeand the description isexception_list[0].value. A deliberately merged group therefore takes the type and message of whichever event arrived first.
Proposed fix
- Add both properties to the property tables in
contents/docs/error-tracking/capture.mdxandcontents/docs/error-tracking/issues-and-exceptions.mdx, with the 255-byte limit and the first-event-wins rule. - State in
contents/docs/error-tracking/grouping-issues.mdxandcontents/docs/error-tracking/fingerprints.mdxthat a custom fingerprint keeps the first event's exception type as the issue name unless the event sets$issue_name. - Decide whether to accept
$exception_issue_nameand$exception_issue_descriptionas 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
- A user who searches the documentation for custom issue naming finds
$issue_name. - The exception property tables list both properties, their truncation limit, and the first-event-wins rule.
- The custom grouping documentation states what names a merged issue.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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