# External links

Attach an external URL — a Datadog trace, Sentry issue, or internal dashboard — to a Brizz session.

Attach an arbitrary URL to a session so you can jump straight from Brizz to the matching record in another tool — a Datadog trace, a Sentry issue, an internal dashboard, a LangSmith run. The link shows up as a clickable badge on the session's detail panel.

This is the explicit, server-SDK counterpart to the auto-detected session-replay badges (see [Sessions](/docs/instrument/sessions.md)): replay badges are detected for you (one per provider), while external links are caller-supplied — you pass the URL, and a session can carry several.

:::info
**External links attach to a session.** Call them inside a session context, or pass the session id explicitly. If no session id can be resolved the call is a safe no-op — it logs a warning and never throws, so telemetry can't break your code.
:::

## Attach a link

Inside a session, the link attaches to the active session automatically — via the session object or the standalone function.

:::tabs
:::tab[Python]
```python
from brizz import add_external_link, start_session

with start_session("session-123") as session:
    # Via the session object.
    session.add_external_link("https://app.datadoghq.com/trace/abc", title="Datadog trace")

    # Or the module-level function — resolves the active session from context.
    add_external_link("https://sentry.io/issues/456", link_type="sentry")
```
:::tab[Node.js]
```typescript
import { addExternalLink, startSession } from '@brizz/sdk';

startSession('session-123', (session) => {
  // Via the session object.
  session.addExternalLink('https://app.datadoghq.com/trace/abc', { title: 'Datadog trace' });

  // Or the top-level function — resolves the active session from context.
  addExternalLink('https://sentry.io/issues/456', { linkType: 'sentry' });
});
```
:::

## Outside a session

If you're not inside a session scope, pass the session id explicitly.

:::tabs
:::tab[Python]
```python
from brizz import add_external_link

add_external_link(
    "https://grafana.example.com/d/abc",
    session_id="session-123",
    title="Grafana dashboard",
    link_type="dashboard",
)
```
:::tab[Node.js]
```typescript
import { addExternalLink } from '@brizz/sdk';

addExternalLink('https://grafana.example.com/d/abc', {
  sessionId: 'session-123',
  title: 'Grafana dashboard',
  linkType: 'dashboard',
});
```
:::

## Options

- **`url`** *(required)* — the link target.
- **`title`** *(optional)* — display text for the badge. Defaults to the URL's host.
- **`link_type` / `linkType`** *(optional)* — a free-form category. Defaults to `generic`.
- **`session_id` / `sessionId`** *(standalone function only)* — the target session. Defaults to the session in context.

Re-sending the same URL is idempotent — it updates the existing link (title and type included). Distinct URLs add separate badges.

## See also

- [Sessions](/docs/instrument/sessions.md) — capture and enrich the session a link attaches to.
- [Sessions in the dashboard](/docs/platform/sessions.md) — where the external-link badge appears.
- [Custom events](/docs/instrument/custom-events.md) — attach business signals to a session.