# Trace
> Waterfall of one request across demo services. Replay sweeps a cursor through time and lights each span while it runs.
- Element: `<sv-trace>`
- React: `import { SvTrace } from "@/components/lumesec/sv-trace"`
- Collection: Service Map (https://elements.lumesec.ai/components/service-map)
- Registry item: https://elements.lumesec.ai/r/sv-trace.json
- Page: https://elements.lumesec.ai/components/service-map/trace



Live preview: https://elements.lumesec.ai/view/sv-trace

```html
<sv-trace></sv-trace>
```

## Installation

```bash
npx shadcn@latest add @lumesec/sv-trace
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/sv-trace.json
```

## Usage

React:

```tsx
import { SvTrace } from "@/components/lumesec/sv-trace";

export function Example() {
  return (
    <SvTrace />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/sv-trace.js"></script>

<sv-trace></sv-trace>
```

## Behaviour

One request through the services as a waterfall. Replay walks a cursor through time and lights each span while it runs.

## API reference

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event    | React prop | Detail              | Description                                                                                                               |
| -------- | ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `select` | `onSelect` | `{ span: string }`  | Fires when a span row is clicked. `span` is the service id of that span; the same id can occur more than once in a trace. |
| `replay` | `onReplay` | `{ trace: string }` | Fires when a replay finishes, with the trace label, for example `GET api.lumesec.local/v1/projects`.                      |

## Accessibility

* The trace switch is a `role="group"` labelled Trace with `aria-pressed` buttons.
* Span rows are buttons with `aria-pressed` for the selection. The selected span's details are in a polite live region.
* The time axis is `aria-hidden`.
* Reduced motion: replay completes in 0.01 s instead of 2.4 s, so the bars fill almost at once.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec`, `--muted` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg`, `--ui-fg2`, `--ui-mono`, `--ui-muted` and `--ui-raised`.

## Notes

* Built-in demo data: two traces with seven spans each, Projects (GET /v1/projects, 46 ms) and Inference (POST /v1/infer, 1.34 s), over services from `INFRA`. No attribute selects a trace.
* Indentation shows call depth.