Skip to content
TraceXDocs
Investigations

Start an investigation

Every way an issue can reach TraceX, from the dashboard to Slack, support email, Jira, Zendesk and on-call alerts, and how to describe an issue so TraceX finds the cause fast.

An investigation is TraceX working one issue through to its root cause. Each one gets an id such as TX48211794554145, a page under Investigations that updates live, and a report at the end.

You can start one by hand from the dashboard, or let issues start investigations on their own from the places your team and customers already report them.

From the dashboard

Section titled “From the dashboard”

Click New investigation (top right, or press ⌘K and search). Describe the problem the way it was reported to you.

What to include

Section titled “What to include”
Include Why it helps Example
What people see Tells TraceX which symptom to explain “Payment fails with card_declined”, “the dashboard shows 0 orders”
Who or what is affected Gives it records to look up an order number, a customer email, a request id, an account id
When it started Narrows logs and suspect changes to the right window “since 09:02 UTC”, “after yesterday’s release”
How widespread Separates one bad record from a general outage “only EU customers”, “every order over $500”

The more specific, the faster TraceX finds it. A good description reads like a message you’d send a colleague:

Since about 09:00 UTC customers can’t finish checkout. Orders stay in pending_capture and the payment page shows “Something went wrong”. Example: order 48213, customer jane@acme.com.

You can also ask about your data in the same box, for example “Which campaign did acme@corp.io run last?”. Questions like that are answered straight away instead of running a full investigation.

From where issues arrive

Section titled “From where issues arrive”

Connect intake integrations and issues start investigations without anyone opening the dashboard. The result goes back to the place the issue came from.

Source How an investigation starts Result goes to
Slack Mention @TraceX in a thread or message it The thread
Gmail support inbox A new thread to the connected address A draft reply you approve
Jira Assign the issue to the TraceX account A comment on the issue
Linear Add the TraceX label A comment on the issue
Zendesk Add the tracex tag An internal note
Intercom Tag the conversation tracex A note for your team
PagerDuty An incident is triggered A note on the incident
Opsgenie An alert at your chosen priority fires A note on the alert
TraceX CLI and AI tools start_investigation from your tool The investigation link

Automatic intake from Jira, Linear, Zendesk, Intercom, PagerDuty and email is part of the Team plan (Plans).

What happens next

Section titled “What happens next”

An investigation moves through three stages:

  1. Triage: TraceX works out what kind of problem it is and where to look.
  2. Diagnosis: it gathers evidence from your databases, code, logs, errors and recent changes, and tests explanations against it.
  3. Fix: when the root cause is grounded, it drafts the change and how to check it.

The page updates live while TraceX works: which agents are running, the queries and searches it makes, and what each found. You get a notification in the dashboard when it finishes. See How TraceX works for the detail.

When an investigation can’t finish

Section titled “When an investigation can’t finish”

Sometimes the evidence isn’t enough, for example when the relevant logs aren’t connected or the description has nothing to look up. The report then says what is missing instead of guessing. Add the source or the detail and start it again.

Duplicates

Section titled “Duplicates”

When the same problem is reported again while an investigation is open, for example by three customers in ten minutes, TraceX links the reports to the open investigation instead of starting from scratch. Everyone gets the same answer.

Limits

Section titled “Limits”

Each plan includes a number of investigations a month (Plans). Admins get an email at 80% and 100%, and a banner shows in the dashboard. See usage any time under Settings → Plan and limits.

Section titled “Related”