Skip to content
TraceXDocs
Get started

Quickstart

Go from a new TraceX account to your first root cause in about ten minutes. Create a project, connect a repository and a database, and run an investigation.

This guide takes you from a new account to a finished investigation. You need three things: access to the TraceX dashboard, one code repository, and read-only access to one database. Logs and errors make answers better but are optional for a first run.

Before you start

Section titled “Before you start”
  • A TraceX account. TraceX is in private beta. Request early access, or ask your team’s admin to invite your email address.
  • Permission to install a GitHub App on the repositories of the system you want TraceX to investigate (or a read-only GitLab or Bitbucket token).
  • A read-only database user, ideally on a read replica. The database pages show the exact commands, for example PostgreSQL.
  • A real issue to try. Something that happened recently works best: a failed order, an error a customer reported, a number that looked wrong.

Set up

Section titled “Set up”

  1. Sign in to the dashboard.

    Open app.tracexpro.com and sign in with your work email, Google, or your company’s single sign-on. If your organization requires two-factor sign-in, you’ll be asked to set it up the first time.

  2. Create a project.

    A project is one product or production system: its databases, repositories, logs and the issues about it. Open the project switcher at the top of the sidebar and create one, named after the product (for example Checkout or Mobile API). If your company runs several unrelated products, make one project for each so investigations only look at the systems that matter. See Projects and organizations.

  3. Connect a repository.

    Go to Integrations → GitHub, click Connect, and install the TraceX GitHub App on the repositories that make up this system. You choose exactly which repositories it can read. GitLab and Bitbucket connect with a read-only access token. See GitHub.

    Why it matters: the code is how TraceX turns an error message into a file and line, and how it finds the change that introduced a problem.

  4. Connect a database.

    Go to Integrations → Databases and add a read-only connection: PostgreSQL, MongoDB, BigQuery or Snowflake. TraceX tests the connection with a real read, stores the credentials encrypted, and reads the schema so it knows which tables and columns exist.

    Why it matters: most issues are about specific records, such as an order, a customer or a payment. With the database, TraceX can look them up instead of guessing.

  5. Add logs and errors (optional, recommended).

    Connect Sentry or a log store such as Datadog, CloudWatch or Loki. With them TraceX can see the exact failure: the exception, how often it happened and since when.

  6. Start an investigation.

    Click New investigation and describe the problem the way a customer or an engineer would. Include what people see, who is affected and when it started:

    Customers report payment failures at checkout since 09:02 UTC. Orders stay in pending_capture. Example: order 48213.

    TraceX triages it, queries the database, reads the code and logs, and writes a report. The page updates live while it works. Most investigations finish in a few minutes.

Read the result

Section titled “Read the result”

When the investigation finishes, its page shows:

  • a summary in plain words and the root cause, with where it is (table, file and line, service),
  • the confidence and what TraceX ruled out,
  • the evidence behind each finding,
  • the fix, how to check it, and a button to open a pull request,
  • a suggested customer reply and a short engineering note.

At the bottom, tell TraceX whether the root cause was right. Corrections become facts it uses next time. See Read a report.

If something doesn’t work

Section titled “If something doesn’t work”
What you see What to do
The database test fails Check the host is reachable from the internet and the user can SELECT. If the database is in a private network, contact support about network access. See Troubleshooting.
The repository doesn’t appear In GitHub, open the TraceX App’s settings and make sure the repository is selected.
The investigation says it couldn’t find evidence Add the missing source (logs or errors often help), or add an identifier like an order id to the description, and run it again.
You hit a plan limit Admins see usage under Settings → Plan and limits. See Plans.

Next steps

Section titled “Next steps”