List every SigNoz trace funnel, with its id, name, and step definitions.

Start here when you have a funnel name but need its id, or to check whether a funnel already exists before creating a duplicate.

Create a SigNoz trace funnel and set its steps in a single call.

This wraps two REST calls (POST /new then PUT /steps/update) and handles the undocumented requirements that make hand-rolling them fail: millisecond timestamps on both, the mandatory timestamp on the update, and omitting each step's id so SigNoz mints a valid UUID. If setting steps fails, the empty funnel is deleted rather than left behind.

Args: name: Funnel name, e.g. "agent-tool-pipeline". steps: Ordered list of at least 2 steps. Each is a dict with:

    * ``service`` (required) -- the service name as it appears in traces
    * ``span`` (required) -- the exact span name
    * ``name`` (optional) -- friendly label for charts
    * ``latency_type`` (optional) -- ``"p90"``/``"p95"``/``"p99"``
      (default ``p99``; **``p50`` is not implemented by SigNoz** and
      silently yields p99 -- you will get a warning back)
    * ``has_errors`` (optional) -- only match errored spans

Example::

    [{"service": "frontend", "span": "GET /cart", "name": "browse"},
     {"service": "payments", "span": "charge", "name": "pay"}]

Returns: funnel_id, the normalized steps, and any warnings.

Note: All steps must occur within the same trace. SigNoz matches the first occurrence of each step and enforces order, so funnels cannot see loops or retries.

Measure a funnel: per-step conversion with trace counts, plus end-to-end metrics.

Identify the funnel by either funnel_id or funnel_name.

Every step row carries an explicit n (number of traces reaching that step) alongside its conversion percentages, so any chart built from this can label each bar with its sample size.

Args: funnel_id: The funnel's UUID. funnel_name: Its name (resolved to an id for you). Ignored if funnel_id is given. time_range: Relative window like "30m", "24h", "7d", "2w". Converted to the nanosecond bounds the API needs.

Returns: steps (one row per step: n, errors, conversion_from_previous_pct, conversion_from_start_pct, dropped_from_previous), end_to_end metrics, and totals.

Note: When zero traces complete a step, SigNoz returns HTTP 500 unsupported value: NaN instead of a 0% result (SigNoz issue #12143). This tool detects that and reports a clean zero, flagged via end_to_end.zero_trace_fallback.

If a step shows 0 traces, read ``diagnostics``. Besides a wrong span
name, the usual culprit is that SigNoz enforces step ordering
**strictly** (``t_next > t_prev``): spans that complete within the same
clock tick -- instantaneous no-ops -- are not counted as ordered and
will silently under-count even when the sequence is correct.

``end_to_end.errors`` is a MAX across steps, not a sum, and its
``latency`` is hardcoded to p99 by SigNoz -- both are restated in
``end_to_end.caveats``.

Fetch the slowest traces for one step transition of a funnel.

Use this after get_funnel_analytics shows a drop-off or a high latency between two steps -- it gives you concrete trace ids to open in SigNoz.

Args: funnel_id: The funnel's UUID. funnel_name: Its name, as an alternative to the id. time_range: Relative window, e.g. "24h". step_start: 1-based index of the transition's first step. step_end: 1-based index of its second step. Must differ from step_start.

Returns: Up to 5 rows of {trace_id, duration_ms, span_count}, plus error_traces sampled from the same transition.

Note: At most 5 rows. SigNoz hardcodes ORDER BY duration_ms DESC LIMIT 5; there is no way to page or raise it. The query is also pairwise -- it measures step_start to step_end only, not the whole funnel.

Permanently delete a trace funnel by id.

Irreversible. Use list_funnels first to confirm you have the right id.