تمرير سياق OpenTelemetry مع الخيوط الافتراضية والتزامن المنظَّم
تعلّم كيف تمرر سياق OpenTelemetry عند العمل مع الخيوط الافتراضية (Virtual Threads) والتزامن المنظَّم (Structured Concurrency).
في OpenTelemetry، يُعد Context عنصرًا أساسيًا: فهو يحمل البيانات الوصفية لسلسلة الاستدعاءات الحالية، مثل التتبع (trace) الجاري تنفيذه حاليًا. وبفضله يمكن ربط عدة نطاقات (spans) في وحدة منطقية واحدة.
افتراضيًا، يمرّر Java OpenTelemetry SDK الـ Context عبر ThreadLocals. فهل ما زال ذلك يعمل كما هو متوقع مع الخيوط الافتراضية والتزامن المنظَّم في Java 21+؟ وإن لم يكن كذلك، فما الذي يحدث بشكل خاطئ؟
الاستدعاءات المتسلسلة
سنبدأ بسيناريو بسيط من الاستدعاءات المتسلسلة، يبدأ كل منها نطاقًا (span). لا توجد خيوط في اللعب بعد، لكنه سيكون خط أساس مفيدًا.
في المثال أدناه، تبدأ دالة أب نطاقًا أبًا وتستدعي دالتين متداخلتين، تبدأ كل منهما نطاقًا متداخلًا خاصًا بها. وهذه هي الشيفرة:
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
import java.util.concurrent.ExecutionException;
public class Demo {
private static Void nested(int id, Tracer tracer) throws InterruptedException {
var span = tracer.spanBuilder("nested-test-span-" + id).startSpan();
try (var scope = span.makeCurrent()) {
Thread.sleep(500);
// pretending to do some work—e.g. sending an HTTP request
} finally {
span.end();
}
return null;
}
private static void parent(Tracer tracer) throws InterruptedException {
var span = tracer.spanBuilder("parent-test-span").startSpan();
try (var scope = span.makeCurrent()) {
nested(1, tracer);
nested(2, tracer);
} finally {
span.end();
}
}
public static void main(String[] args) throws InterruptedException, ExecutionException {
var otel = AutoConfiguredOpenTelemetrySdk.initialize();
// span
var tracer = otel.getOpenTelemetrySdk().getTracer("otel-demo");
parent(tracer);
// make sure telemetry is sent
Thread.sleep(1000);
}
}
تهيّئ الدالة main مكتبة OpenTelemetry من متغيرات البيئة. وهي مفيدة للاختبار:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_METRIC_EXPORT_INTERVAL=500
OTEL_SERVICE_NAME=demo
يجب أن تشير نقطة نهاية المُصدِّر (exporter) إلى نسخة قيد التشغيل – مثل LGTM من Grafana، وهو إعداد Docker بسيط بحاوية واحدة. وهذا هو ملف docker-compose.yml المقابل:
services:
# OpenTelemetry Collector, Prometheus, Loki, Tempo, Grafana
observability:
image: 'grafana/otel-lgtm'
ports:
- '3000:3000' # Grafana's UI
- '4317:4317' # Exporter
يمنحنا هذا مُصدِّرًا وواجهة مستخدم تسهّل تصور نتائج الاختبار.
تبدأ الدالة parent نطاقًا وتستدعي nested مرتين، ويبدأ كل استدعاء نطاقًا فرعيًا. وبعد تشغيل المثال، ينبغي أن تعرض الواجهة شيئًا كهذا:
حتى الآن، كل شيء يعمل. لنُدخل الآن بعض التوازي.
الاستدعاءات المتوازية
عندما لا تعتمد الاستدعاءات المتداخلة بعضها على بعض وتستغرق وقتًا ملحوظًا (مثلًا لأنها تجري عمليات إدخال/إخراج)، قد نرغب في تشغيلها بالتوازي. ويمكن فعل ذلك بعدة طرق، لكننا سنتبع المسار الذي رسمه JEP التزامن المنظَّم في Java (متاح كمعاينة منذ Java 21).
هنا سنستخدم ببساطة الواجهة البرمجية StructuredTaskScope. والخاصية الجوهرية للتزامن المنظَّم أن عمر الخيوط التي تنفذ المهام الفرعية يتحدد بالبنية النحوية للشيفرة.
وبعبارة أخرى، لأن StructuredTaskScope موجود داخل try (var scope = span.makeCurrent())، فإن كل خيط يبدأ في نطاق المهام مضمون الانتهاء بحلول وقت إغلاق نطاق الرصد (observability scope) والـ span:
private static Void nested(int id, Tracer tracer) throws InterruptedException {
var span = tracer.spanBuilder("nested-test-span-" + id).startSpan();
try (var scope = span.makeCurrent()) {
Thread.sleep(500);
} finally {
span.end();
}
return null;
}
private static void parent(Tracer tracer) throws InterruptedException, ExecutionException {
var span = tracer.spanBuilder("parent-test-span").startSpan();
try (var scope = span.makeCurrent()) {
try (var taskScope = new StructuredTaskScope.ShutdownOnFailure()) {
Supplier<Void> n1 = taskScope.fork(() -> nested(1, tracer));
Supplier<Void> n2 = taskScope.fork(() -> nested(2, tracer));
taskScope.join().throwIfFailed();
n1.get();
n2.get();
}
} finally {
span.end();
}
}
تطلق الشيفرة أعلاه مهمتين في الخلفية ثم تنتظر انتهاءهما معًا بـ .join(). وهي تشبه العمل مع العقود المستقبلية (futures)، لكنها تضيف ضمانًا: إذا فشلت إحدى المهمتين، فلا تُترك الأخرى «معلَّقة» بل تُقاطَع.
لكن عندما نشغّل هذا المثال، لا يعود سياق الرصد يُمرَّر. وبدلًا من تتبع واحد مترابط، ينتهي بنا الأمر بثلاثة تتبعات منفصلة:
وبفضل التوازي، يستغرق نطاق الأب الآن 500 ملّي ثانية إجمالًا، لكننا فقدنا الرصد على العملية بأكملها.
الاستدعاءات المتوازية، مع الرصد
ما الذي يسير بشكل خاطئ؟ تذكّر أن Context في OpenTelemetry ينتقل عبر ThreadLocals. وهذا مثالي لربط الاستدعاءات والنطاقات داخل خيط واحد، لكنه ينهار حالما تتدخل عدة خيوط – سواء كانت «عادية» (أي خيوط «المنصة») أو افتراضية. والسبب أن ThreadLocals لا تُورَّث.
تحاول OpenTelemetry معالجة ذلك بعدة طرق. فيمكنك مثلًا تغليف Executor بـ Context.taskWrapping()، بحيث يُمرَّر السياق إلى كل مهمة تُطلق عبر ذلك المنفِّذ. أما بالنسبة إلى التزامن المنظَّم، فلا توجد أدوات كهذه (بعد) – ولسبب وجيه، إذ ما زالت الواجهة البرمجية في مرحلة المعاينة.
لذا علينا تنفيذ التمرير بأنفسنا. أحد الخيارات توفير ThreadFactory عند إنشاء StructuredTaskScope. ويمكن لمصنع مخصص كهذا أن يتولى تمرير السياق يدويًا – أي أننا ننفّذ يدويًا وراثة القيمة المحلية للخيط التي تحمل السياق:
static class PropagatingVirtualThreadFactory implements ThreadFactory {
private ThreadFactory delegate = Thread.ofVirtual().factory();
@Override
public Thread newThread(Runnable r) {
var parentContext = Context.current();
return delegate.newThread(() -> {
parentContext.makeCurrent();
r.run();
});
}
}
يلتقط مصنعنا المخصص أولًا السياق الحالي بـ Context.current() لحظة إنشاء خيط جديد. ثم ينشئ خيطًا افتراضيًا جديدًا (مفوِّضًا إلى Thread.ofVirtual().factory() الذي يوفره JDK)، وقبل تنفيذ كتلة الشيفرة يجعل السياق الملتقَط «حاليًا» – هذه المرة داخل الخيط الجديد.
لا يلزم سوى تغييرات طفيفة في الدالة parent:
private static void parent(Tracer tracer) throws InterruptedException, ExecutionException {
var span = tracer.spanBuilder("parent-test-span-1").startSpan();
try (var scope = span.makeCurrent()) {
try (var taskScope = new StructuredTaskScope.ShutdownOnFailure(null,
new PropagatingVirtualThreadFactory())) {
Supplier<Void> n1 = taskScope.fork(() -> nested(1, tracer));
Supplier<Void> n2 = taskScope.fork(() -> nested(2, tracer));
taskScope.join().throwIfFailed();
n1.get();
n2.get();
}
} finally {
span.end();
}
}
وعند تشغيل المثال الآن تظهر النطاقات مترابطة داخل تتبع واحد من جديد:
ماذا عن ScopedValues؟
إلى جانب JEP التزامن المنظَّم، أدخلت Java أيضًا الواجهة البرمجية ScopedValue (انظر JEP) – وهي جيل جديد من ThreadLocal تُورَّث إلى الخيوط الافتراضية الفرعية عند إنشائها.
القيم المحدودة النطاق (scoped values) مخصصة للاستخدام بطريقة منظَّمة مع StructuredTaskScopes. وإليك مثالًا مأخوذًا من JEP:
private static final ScopedValue<String> X = ScopedValue.newInstance();
void foo() {
where(X, "hello").run(() -> bar());
}
void bar() {
System.out.println(X.get()); // prints hello
where(X, "goodbye").run(() -> baz());
System.out.println(X.get()); // prints hello
}
void baz() {
System.out.println(X.get()); // prints goodbye
}
تذكّر أنه لا يمكن إعطاء ScopedValue قيمة جديدة إلا أثناء تقييم كتلة الشيفرة الممرَّرة عبر where(...).run(...). ومرة أخرى، يُحدَّد العمر بالبنية النحوية للشيفرة – هذه المرة عمر ربط القيمة، بينما كان سابقًا عمر الخيط.
لهذا التصميم خصائص جذابة، لكنه لا يصلح لتنفيذ بديل لـ ContextStorage في OpenTelemetry. فالتنفيذات لتلك الواجهة تخزّن سياق OpenTelemetry وتمرّره، وكما ذُكر سابقًا، فإن ThreadLocalContextStorage هو الافتراضي.
قد يبدو مغريًا كتابة تنفيذ ScopedValueContextStorage بحيث يُمرَّر السياق تلقائيًا إلى الخيوط الافتراضية الفرعية المنشأة حديثًا؛ لكن الواجهة البرمجية لتخزين السياق غير منظَّمة:
public interface ContextStorage {
Scope attach(Context toAttach);
Context current();
}
والسياق المرفق بمخزن لا يلزمه أن يعيش وفق بنية الشيفرة (رغم أن هذا ما يحدث عادةً مع بنية try-with-resources). فالدالة attach تعيد Scope بدلًا من ذلك، ويمكن للشيفرة إغلاقه في أي لحظة تشاء.
وبسبب هذا التصميم، تتعارض القيم المحدودة النطاق وتخزين السياق تعارضًا جوهريًا.
الخلاصة
«بشكل افتراضي»، لا يقدم OpenTelemetry Java SDK أي تكامل مع الخيوط الافتراضية يتجاوز تمرير السياق داخل خيط واحد.
لكن الخيوط الافتراضية مصممة لتشجيع إنشاء تفرعات جديدة بحرية توازي تنفيذ الشيفرة وترفع أداء الخدمات المعنية / معدل معالجتها. ونتيجة لذلك يضيع سياق القياس عن بُعد (telemetry)، وتُبلَّغ النطاقات غير المترابطة كتتبعات منفصلة بدلًا من تتبع واحد مجمَّع.
ويمنع التمرير اليدوي للسياق ذلك. وفي أبسط صوره، تلتقط السياق الأب قبل تفريع عملية حسابية وتعيّنه من جديد في الخيط الفرعي. ويتيح لك ThreadFactory مخصص، يعمل أيضًا مع الواجهة StructuredTaskScope، أتمتة هذا التمرير إلى حد ما.
وأخيرًا، ما لم يتغير تصميم ContextStorage، يبدو من المستحيل بناء تنفيذ يعتمد على ScopedValues القادمة. فهي تحل مشكلة الوراثة، لكنها تتطلب أيضًا استخدامًا منظَّمًا يجب أن يتطابق مع البنية النحوية للشيفرة – وهذا يتعارض مع طريقة عمل ContextStorage.