# Dùng SDK Sentry cho lỗi khi OpenTelemetry làm chủ tracing

> Một bên làm chủ tracing và cầu nối để lỗi mang trace ID: Sentry 10 và 11 cho Node.js, OTLPIntegration cho Python, sentry-go, sentry-java.

Nhiều dịch vụ đã dùng SDK Sentry cho lỗi. Hãy giữ nó — Belvador nhận các lỗi đó nguyên như vậy — và để OpenTelemetry làm chủ tracing. Có hai việc tách biệt, và cả hai đều cần:

1. **Một bên làm chủ tracing.** Chỉ OpenTelemetry tạo span. SDK Sentry tắt tracing: không `tracesSampleRate`, `traces_sample_rate` hay `TracesSampleRate`, không integration hiệu năng của Sentry.
2. **Lỗi mang ID của span đang chạy.** Tắt tracing của Sentry không tự làm lỗi đọc context của OpenTelemetry. Mỗi SDK có một cầu nối nhỏ cho việc đó; thiếu nó thì lỗi và trace vẫn được lưu nhưng không khớp với nhau.

Giữ exporter OpenTelemetry hiện có trỏ tới Belvador. Các ví dụ của Sentry dựng endpoint OTLP từ DSN là để gửi span tới Sentry; bỏ qua các phần đó.

## SDK Belvador

Các gói `@belvador/*` chỉ gửi lỗi và không bao giờ tạo span. Truyền API OpenTelemetry qua tuỳ chọn `otel` thì lỗi mang ID của span đang chạy — đã kiểm trên Node.js và Cloudflare Workers: [Liên kết request](https://belvador.dev/vi/docs/sdk/tracing#khi-da-dung-opentelemetry).

## Node.js (`@sentry/node`)

**Sentry 11** (phát hành tháng 9/2026) có integration riêng: gắn event vào context OpenTelemetry đang chạy, không gửi span và để OpenTelemetry lo việc lan truyền. Khởi động SDK OpenTelemetry trước, rồi:

```js
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  enableOpenTelemetrySetup: false,
  integrations: [Sentry.openTelemetryIntegration()],
  // không tracesSampleRate
});
```

**Sentry 10** không có integration này. Cách cài chỉ-lỗi của nó dùng `skipOpenTelemetrySetup: true` và gắn context manager, sampler, propagator của Sentry vào SDK OpenTelemetry của bạn, làm thay đổi cách tiến trình lấy mẫu và lan truyền. Nên nâng lên 11, hoặc dùng tuỳ chọn `otel` của SDK Belvador.

## Python (`sentry-sdk`)

`OTLPIntegration` (sentry-sdk 2.45.0 trở lên) cho lỗi dùng trace và span OpenTelemetry đang chạy. Mặc định nó còn cài exporter tới Sentry và thay propagator toàn cục; tắt cả hai để phần cài của bạn vẫn làm chủ:

```python
import sentry_sdk
from sentry_sdk.integrations.otlp import OTLPIntegration

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    integrations=[
        OTLPIntegration(
            setup_otlp_traces_exporter=False,
            setup_propagator=False,
        ),
    ],
    # không traces_sample_rate
)
```

Cài bằng `pip install "sentry-sdk[opentelemetry-otlp]"`. Cách cũ `instrumenter="otel"` với `SentrySpanProcessor` và `OpenTelemetryIntegration` đã bị ngừng khuyến nghị.

## Go (`sentry-go`)

`sentryotel.NewOtelIntegration()` (sentry-go 0.45.0 trở lên) lấy trace ID từ một `context.Context` của Go — Go không có span đang chạy ngầm, nên context phải tới được lệnh capture:

```go
sentry.Init(sentry.ClientOptions{
    Dsn: os.Getenv("SENTRY_DSN"),
    Integrations: func(in []sentry.Integration) []sentry.Integration {
        return append(in, sentryotel.NewOtelIntegration())
    },
})

// ctx mang span của request (từ otelhttp)
hub := sentry.GetHubFromContext(ctx)
if hub == nil {
    hub = sentry.CurrentHub()
}
hub.Client().CaptureException(err, &sentry.EventHint{Context: ctx}, hub.Scope())
```

Gọi trơn `sentry.CaptureException(err)` thì không thấy span. `NewSentrySpanProcessor` bị ngừng khuyến nghị ở 0.45.0 và bị gỡ ở 0.47.0.

## Java (`sentry-java`)

Khi OpenTelemetry Java agent thường làm chủ span, thêm module `sentry-opentelemetry-otlp` (8.34.0 trở lên) và event processor của nó:

```java
Sentry.init(options -> {
    options.setDsn(System.getenv("SENTRY_DSN"));
    options.addEventProcessor(new OpenTelemetryOtlpEventProcessor());
    // không tracesSampleRate
});
```

Đừng gắn thêm `sentry-opentelemetry-agent`: đó là agent thứ hai có instrumentation riêng. `SENTRY_AUTO_INIT=false` chỉ ngăn agent đó tự khởi tạo Sentry; không phải công tắc chỉ-lỗi.

## Belvador đã chạy những gì

Cầu nối `otel` của SDK Belvador đã được kiểm, và từng cách cài Sentry ở trên cũng vậy. Mỗi trường hợp là một dịch vụ HTTP nhỏ để OpenTelemetry làm chủ span, giữ SDK Sentry cho lỗi đúng như trên, gửi một lỗi mỗi request tới Belvador, và lỗi nằm trên span của request; bỏ integration (hoặc event processor) thì cùng lỗi đó nằm ngoài trace:

| SDK | Đã kiểm với | Kết quả |
|---|---|---|
| Node.js (`@sentry/node`) | node 22.23.4, @opentelemetry/sdk-node 0.300.0, @opentelemetry/auto-instrumentations-node 0.82.0, pino 10.4.0, @sentry/node 11.8.0 | Lỗi nằm trên span của request (2026-10-25) |
| Python (`sentry-sdk`) | python 3.12.15, opentelemetry-distro 0.66b1, opentelemetry-sdk 1.45.1, flask 3.1.3, sentry-sdk 2.72.0 | Lỗi nằm trên span của request (2026-10-25) |
| Go (`sentry-go`) | go 1.27.3, go.opentelemetry.io/otel v1.47.0, otelhttp v0.72.0, otelslog v0.21.0, sentry-go v0.50.0, sentry-go/otel v0.50.0 | Lỗi nằm trên span của request (2026-10-25) |
| Java (`sentry-java`) | java 21.0.12.1, opentelemetry-javaagent 2.32.0, sentry-java 8.61.0, sentry-opentelemetry-otlp 8.61.0, opentelemetry-api 1.66.0 | Lỗi nằm trên span của request (2026-10-25) |

[Bảng năng lực](https://belvador.dev/vi/docs/reference/capabilities) ghi chúng ở cột **Header trace**. Với Maven hoặc Gradle, module Java tự kéo `opentelemetry-api` và các phụ thuộc của nó; nếu tự ghép classpath, `opentelemetry-context` cần thêm `opentelemetry-common`. Sau khi cài, kiểm một lỗi trên trace của nó: liên kết **Trace** của issue phải mở được waterfall của request.