Index of every page on this site: llms.txt
All skills
launchdarkly avatar

/investigate

@f0ee110 official
Run it yourself

Finds the root cause of a production problem from observability data (logs, traces, errors, sessions, metrics): scope and onset, what changed (deploys and flag changes), which host, version, route or flag variation is over-represented against a baseline, then trace, log and error evidence and blast radius. Use when the user reports a bug, an outage, an error or latency spike, an incident, or asks about patterns across application data.

Use this Skill: https://skilld.dev/gh/launchdarkly/ai-tooling/investigate

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

relationship-search.md

≈2.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Relationship search: span(...), log(...), and THEN

Load this file when a search-sessions question depends on how events relate to each other: "did A happen and then B?", "did A happen but never B?", "which sessions had both A and B?", "either A or B?".

Plain filters such as visited-url=*/pricing* visited-url=*/checkout* only check that a session matched each filter, in any order and not necessarily on the same event. Relationship search wraps each event in its own block and joins the blocks with AND, OR, or THEN. Never tell the user that event order or absence cannot be checked; use this syntax instead.

Blocks

Block Matches
span(A) at least one span matching A in the session
no_span(A) no span in the session matches A
log(A) at least one log matching A, recorded during the session
no_log(A) no log matches A during the session

This file covers relationship search in search-sessions. search-traces takes a smaller form within one trace: span(A) THEN span(B), span(A) THEN no_span(B), and the top-level any_span(...), child_span(...), parent_span(...) and root_span(...); see traces.md. The log(...) blocks are sessions only.

In Session Replay search, every page view, click, network request, track call, and flag evaluation is stored as a span, so span(...) covers frontend events as well as backend spans. Log blocks only join logs recorded with the session's secure_session_id. Frontend console logs carry it. Backend logs carry it only when the SDK propagated the session to that request.

Operators between blocks

All three operators join blocks. Pick the one that matches the question:

Query Meaning
span(A) span(B) or span(A) AND span(B) Both happened, in any order. The two blocks may match the same event.
span(A) OR span(B) Either happened.
span(A) THEN span(B) A happened, and strictly later B happened. Chains can be longer: span(A) THEN span(B) THEN span(C).
span(A) THEN no_span(B) Drop-off: A happened and B never happened after the first A.
span(A) no_span(B) A happened and B never happened anywhere, before or after.

Span and log blocks are interchangeable, so they mix freely: span(A) THEN log(B), span(A) OR log(B), log(A) THEN no_log(B).

Precedence, tightest first: THEN, then AND / whitespace, then OR. country=US span(A) THEN span(B) has_rage_clicks=true parses as country=US AND (span(A) THEN span(B)) AND has_rage_clicks=true. Use parentheses to group OR alternatives.

Where to put OR

Prefer OR inside a single block when the alternatives are the same kind of event. It scans once instead of joining twice:

span(span_name="click" event.text=("Pay Now" OR "Complete Order")) THEN span(has_errors=true OR http.status_code>=500)

Use OR between blocks when the alternatives are different kinds of events, such as a span versus a log, or two different sequences:

span(http.url=*/api/pay* http.status_code>=500) OR log(level=error message=*payment*)
(span(view_name="/signup") THEN span(has_errors=true)) OR (span(view_name="/login") THEN span(has_errors=true))

Two scopes: session keys vs. span keys

Everything outside a block filters the whole session. Everything inside a block filters one event. The keys are different. A session key written inside span(...) still parses, but it silently matches nothing, so convert it first:

Session key (outside blocks only) Inside span(...)
visited-url=*/checkout* view_name="/checkout" (web path or mobile screen name) or url.full=*/checkout*
clickTextContent="Pay Now" span_name="click" event.text="Pay Now"
clickSelector=... span_name="click" with event.id, event.classname, or event.xpath
clickTarget=BUTTON span_name="click" event.tag="BUTTON"
event="order_completed" (custom track event) span_name="track" key="order_completed"
has_errors=true has_errors=true (an error on that event)

Session keys with no span equivalent (country, browser_name, os_name, identifier, email, length, active_length, has_rage_clicks, first_time, viewed_by_me, environment, ...) stay outside the blocks: country=US span(A) THEN span(B).

Canonical span recipes

  • Page or screen view: span(view_name="/checkout"). view_name holds the path only; to match a host or query string, use span(span_name="page_view" url.full=*...*).
  • Click: span(span_name="click" event.text="Pay Now"). Add url.full=*/checkout* inside the same block to pin the page.
  • Network request: span(http.method=POST http.url=*/api/checkout* http.status_code>=500). duration>3s also works.
  • Custom track event: span(span_name="track" key="order_completed"). Don't use event.name, which is the mobile screen name.
  • Error: span(has_errors=true) or span(service_name="payment-service" has_errors=true).
  • Flag evaluation: span(feature_flag.key="new-checkout" feature_flag.result.value="true"). Values are JSON-encoded, so match a string variation with an unquoted wildcard: feature_flag.result.value=*treatment*.

Inside log(...), use log keys: level, message, source, service_name, or any log attribute. A bare word searches the message: log(timeout).

The normal filter grammar applies inside a block: =, !=, <, >, EXISTS, value groups like (500 OR 502), and unquoted wildcards. A * inside quotes is a literal asterisk. Duration suffixes need whole integers (1500ms, not 1.5s).

Examples

# Visited /pricing, then /checkout
span(view_name="/pricing") THEN span(view_name="/checkout")

# Clicked "Pay Now", then the app logged a payment error
span(span_name="click" event.text="Pay Now") THEN log(level=error message=*payment*)

# Checkout funnel drop-off: clicked "Pay Now" and never completed the order
span(view_name="/checkout") THEN span(span_name="click" event.text="Pay Now") THEN no_span(span_name="track" key="order_completed")

# Visited /pricing and never clicked "Contact Sales" anywhere in the session
span(view_name="/pricing") no_span(span_name="click" event.text="Contact Sales")

# Both happened, in any order
span(feature_flag.key="new-editor" feature_flag.result.value="true") span(service_name="document-service" duration>5s)

# US mobile users who either cancelled or hit a failing delete-account request
os_name=(iOS OR Android) country=US (span(span_name="click" event.text="Cancel Subscription") OR span(http.method=DELETE http.url=*/api/account*))

# Clicked "Save" twice (THEN guarantees two distinct events)
span(span_name="click" event.text="Save") THEN span(span_name="click" event.text="Save")

Rules the parser enforces

  • THEN only joins blocks, never plain filters. Write country=US span(A), not country=US THEN span(A).
  • A THEN chain must start with span(...) or log(...). For "B never happened, and A did", write span(A) no_span(B).
  • THEN no_span(...) / THEN no_log(...) may only be the last step. "A, then C, with no B in between" is not expressible.
  • NOT cannot precede a block or a chain. Use no_span(...) / no_log(...) instead. span(NOT x) means "some event that isn't x", which almost every session has.
  • Blocks cannot be nested, and a parenthesized group cannot follow THEN. Expand span(A) THEN (span(B) OR span(C)) into (span(A) THEN span(B)) OR (span(A) THEN span(C)), or merge B and C into one block with a value group.
  • OR between a block and a plain session filter is rejected. country=US span(A) OR span(B) is also rejected, because it parses as (country=US AND span(A)) OR span(B). Wrap the alternatives: country=US (span(A) OR span(B)).

Not supported

Don't invent syntax for these. Rewrite to the closest supported form and tell the user what was dropped:

  • Time bounds ("B within 10 seconds of A"): there is no WITHIN. THEN means "later, with no upper bound".
  • Counts ("clicked Retry at least 3 times"): there is no count operator. Chain THEN once per occurrence for small numbers.
  • Ordering across sessions: every block is scoped to one session.

Interpreting results

  • THEN anchors on the earliest match of each step. A session that did A, then B, then A again with no B afterwards is not a span(A) THEN no_span(B) drop-off, because B followed the first A.
  • THEN needs strictly increasing timestamps. Two events written with the same timestamp, such as a page view and a flag evaluation that fires on load, never satisfy THEN in either order.
  • Every block is limited to the query's time range. A B that happened just outside the window is invisible, so near-the-edge drop-offs can be false positives.
  • Exact matches are case- and whitespace-sensitive. When the user's wording is approximate, use a case-insensitive regex: event.text=/pay now/i.
  • Span-based blocks need the SDK's tracing instrumentation. If a project has session keys like clickTextContent but span(span_name="click" ...) returns nothing, the project may be on an older SDK or have tracing off. Say so rather than reporting zero matches as a finding.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2d3 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    This skill provides specialized instructions for investigating production outages and performance issues using the LaunchDarkly observability platform. It provides a structured methodology for identifying root causes through log analysis, trace inspection, and error grouping, utilizing the official LaunchDarkly MCP server.

  • Socket2d

    No alerts

  • Snyk2d

    Risk: MEDIUM · 1 issue

Signed by skilld at f0ee110. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
compatibility
Requires the remotely hosted LaunchDarkly MCP server
metadata
{
  "author": "launchdarkly",
  "version": "0.5.0"
}

README badge

README badge for launchdarkly/ai-tooling/investigate