Skip to content

docs(sdk): add Hub/Scope and Client steps to metrics and logs #16457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
philipphofmann wants to merge 4 commits into
base: master
Choose a base branch
from
Open

docs(sdk): add Hub/Scope and Client steps to metrics and logs #16457

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1042e86
docs(sdk): add Hub/Scope steps to metrics SDK behavior
philipphofmann Feb 19, 2026
2638c36
Merge branch 'master' into philipp/docs-sdk-metrics-hub-scope
philipphofmann Feb 25, 2026
b11437a
Merge branch 'master' into philipp/docs-sdk-metrics-hub-scope
philipphofmann Feb 26, 2026
f4c617f
docs(sdk): use generic captureMetric/captureLog for Hub/Scope
philipphofmann Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions develop-docs/sdk/telemetry/logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Log processing **MUST** follow this order:

1. Capture log via [Public APIs](#logger-module) (e.g. `Sentry.logger.info`) or via [SDK integrations](#sdk-integrations).
2. Check if logging is enabled via `enableLogs`/`enable_logs` — if not, skip remaining steps.
3. Pass the log to Hub/Scope, which **MUST** offer the same methods as the static API `Sentry.logger.X`.
3. Pass the log to Hub/Scope via a generic method (e.g., `captureLog(log, scope)`).
Copy link
Member

@cleptric cleptric Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no e.g., this has to be called captureLog. Not sure why scope would be a parameter in general, should likely be scope.captureLog()

4. Pass the log to the Client via a generic method (e.g., `captureLog(log, scope)`).
5. Process captured log (attach attributes per [Default Attributes](#default-attributes)).
6. Run `beforeSendLog`/`before_send_log` to filter or modify the log.
Expand Down Expand Up @@ -461,9 +461,11 @@ SDKs **MUST** expose logging methods in a `logger` module or namespace, with one

These methods accept a string template and parameters for structured logging. They **MAY** also accept arbitrary attributes.

The Hub/Scope **MUST** offer the same methods as the static `Sentry.logger.X` API (since 1.10.0). The Client **SHOULD** only offer one generic method (e.g., `captureLog(log, scope)`).
Furthermore:

SDKs **MAY** add additional helpers (e.g., decorators, string template helpers) as appropriate for their platform.
1. The Hub/Scope and Client **MUST** offer a generic method for capturing logs (e.g., `captureLog(log, scope)`).
1. The Hub/Scope **MAY** offer the same methods as the static `Sentry.logger.X` API (since 1.10.0).
Copy link
Member

@cleptric cleptric Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, we do not want this.

1. SDKs **MAY** add additional helpers (e.g., decorators, string template helpers) as appropriate for their platform.
Copy link
Member

@cleptric cleptric Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not precise enough. We will get questions in a month what this means.


</SpecSection>

Expand Down
15 changes: 11 additions & 4 deletions develop-docs/sdk/telemetry/metrics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,10 +97,12 @@ Metric processing **MUST** follow this order:

1. Capture metric via [Public APIs](#metrics-module) (e.g. `Sentry.metrics.count`).
2. Check if metrics are disabled as per `enableMetrics`/`enable_metrics` configuration — if so, skip the rest of the steps.
3. Process captured metric (attach default attributes as per [Default Attributes](#default-attributes)).
4. Run `beforeSendMetric`/`before_send_metric` to filter or modify the metric.
5. Add metric to buffer/batch processor as detailed in [Buffering](#buffering).
6. At time of flushing buffer, send array of metrics to Sentry via `trace_metric` envelope, apply rate limiting as per [Data Category and Rate Limiting](#data-category-and-rate-limiting).
3. Pass the metric to Hub/Scope via a generic method (e.g., `captureMetric(metric, scope)`).
4. Pass the metric to the Client via a generic method (e.g., `captureMetric(metric, scope)`).
5. Process captured metric (attach default attributes as per [Default Attributes](#default-attributes)).
6. Run `beforeSendMetric`/`before_send_metric` to filter or modify the metric.
7. Add metric to buffer/batch processor as detailed in [Buffering](#buffering).
8. At time of flushing buffer, send array of metrics to Sentry via `trace_metric` envelope, apply rate limiting as per [Data Category and Rate Limiting](#data-category-and-rate-limiting).

</SpecSection>

Expand Down Expand Up @@ -319,6 +321,11 @@ SDKs **MUST** expose metrics methods in a `metrics` module or namespace. At mini
- `attributes` **Object, optional** — a dictionary of attributes (key-value pairs with type information).
- `scope` **Scope, optional** — the scope to capture the metric with.

Furthermore:

1. The Hub/Scope and Client **MUST** offer a generic method for capturing metrics (e.g., `captureMetric(metric, scope)`).
1. The Hub/Scope **MAY** offer the same methods as the static `Sentry.metrics.X` API.

</SpecSection>

### Threading and Concurrency Considerations
Expand Down
Loading