Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
28 changes: 10 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ Java реализация [Библиотеки RPC вызовов][rpc-lib] д
## Ключевые возможности

- Сквозная трассировка вызовов через `TraceData`, автоматическое измерение
длительности и интеграция со SLF4J MDC и OpenTelemetry.
- Расширенный MDC: автоматически публикует идентификаторы Woody/OTel, дедлайны,
длительности и интеграция со SLF4J MDC.
- Расширенный MDC: автоматически публикует идентификаторы Woody, дедлайны,
RPC-метаданные и может отключаться через `-Dwoody.mdc.extended=false`.
- Потокобезопасная обработка фоновых задач с сохранением контекста
(`WFlow.create`, `createServiceFork`).
Expand Down Expand Up @@ -57,14 +57,14 @@ _woody-pom_ и в корневой директории проекта выпо
`woody-api`, интеграция `woody-thrift`, а также пропатченный `libthrift`
(форк Apache Thrift, переиспользующий HttpClient5 и подключающийся как
модуль).
- Основной стек: Java 11, SLF4J, Apache Commons Pool 2, OpenTelemetry
(API/SDK/OTLP), Jakarta Servlet 5, Jetty и EasyMock в тестах.
- Основной стек: Java 11, SLF4J, Apache Commons Pool 2, Jakarta Servlet 5,
Jetty и EasyMock в тестах.

## Woody API

- `TraceContext`/`TraceData` управляют client/service span’ами в
`ThreadLocal`, автоматически создают `trace_id/span_id`, фиксируют
длительность, синхронизируют SLF4J MDC и завершают OTEL-спаны.
длительность и синхронизируют SLF4J MDC.
- `WFlow` и `flow.concurrent` оборачивают `Runnable`/`Callable`/
`ExecutorService`, сохраняя контекст при выполнении в других потоках,
поддерживают форки с новыми root- и service-span’ами.
Expand All @@ -88,7 +88,7 @@ _woody-pom_ и в корневой директории проекта выпо
- Thrift over HTTP поверх Woody.
- Клиенты (`THClientBuilder`, `THSpawnClientBuilder`,
`THPooledClientBuilder`) создают `TServiceClient`, добавляют
транспортные и message перехватчики (метаданные, traceparent, события),
транспортные и message перехватчики (метаданные, события),
управляют ресурсами HttpClient5.
- Сервисы (`THServiceBuilder`) собирают `TServlet` с обёртками над
`TProcessor`, прокидывая `TraceContext.forService`, подключая
Expand All @@ -98,8 +98,7 @@ _woody-pom_ и в корневой директории проекта выпо
- Транспорт и сообщения расширяются через bundles
(`MetadataExtensionBundle` и др.), создавая `THCExtensionContext`/
`THSExtensionContext` для клиента и сервиса.
- Поддержка W3C traceparent (`TraceParentUtils`), заполнение
дедлайнов/ошибок в метаданные, HTTP-логгеры.
- Заполнение дедлайнов/ошибок в метаданные, HTTP-логгеры.
- Дополнительные пакеты: `error` (конвертация исключений и
HTTP-статусов), `event` (логирование), `transport` (конфигурация HTTP
servlet’ов и клиентов).
Expand All @@ -115,16 +114,9 @@ _woody-pom_ и в корневой директории проекта выпо
- `woody-api/src/test` покрывает генераторы идентификаторов, трассировку и
прокси.
- `woody-thrift/src/test` (Jetty quickstart + EasyMock) проверяет
HTTP-интеграцию, обработку исключений и метаданные, включая
интеграционные сценарии `TraceLifecycleIntegrationTest` для проверки
сквозной OpenTelemetry-трассировки, восстановления контекста, ошибок и
работы с неполными заголовками.
HTTP-интеграцию, обработку исключений и метаданные.
- Профиль `gen_thrift_classes` включает `thrift-maven-plugin` для генерации
Thrift IDL.
- Интеграционные тесты `MetadataMdcPropagationTest` и
`TraceLifecycleIntegrationTest` контролируют перенос MDC-метаданных,
OpenTelemetry-трассировку и восстановление контекста при ошибках.

## Дополнительные материалы

- [Контекст Woody Java](context.md) — сводный обзор модулей,
Expand All @@ -134,8 +126,8 @@ _woody-pom_ и в корневой директории проекта выпо

Реализация обеспечивает сквозную трассировку, управление временем жизни
span’ов и доступ к событиям через единую API-обвязку; `woody-thrift` поверх
неё инкапсулирует создание HTTP-клиентов и сервисов Thrift с `traceparent`,
логированием и расширяемыми метаданными, опираясь на локально
неё инкапсулирует создание HTTP-клиентов и сервисов Thrift с логированием и
расширяемыми метаданными, опираясь на локально
модифицированный `libthrift`.

[rpc-lib]: http://52.29.202.218/design/ms/platform/rpc-lib/
27 changes: 10 additions & 17 deletions context.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@
- Maven multi-module library delivering RPC tracing infrastructure for
microservices.
- Java 11 baseline; core dependencies include SLF4J, Apache Commons Pool 2,
OpenTelemetry (API/SDK/OTLP exporter), Jakarta Servlet 5, HttpClient5, Jetty
(tests), EasyMock.
Jakarta Servlet 5, HttpClient5, Jetty (tests), EasyMock.
- Modules share version `woody` (root POM); `dependencyManagement` keeps `woody-
api` version-aligned.

Expand All @@ -15,9 +14,8 @@
### woody-api

- Thread-local tracing via `TraceContext`/`TraceData` managing client/service
spans, auto ID generation, duration tracking, SLF4J MDC sync, OTEL span
lifecycle.
- `MDCUtils` публикует trace/span идентификаторы Woody и OpenTelemetry,
spans, auto ID generation, duration tracking and SLF4J MDC sync.
- `MDCUtils` публикует trace/span идентификаторы Woody,
дедлайны и RPC-метаданные (отключаемо через системное свойство
`woody.mdc.extended`).
- Concurrency helpers (`WFlow`, `WCallable`, `WRunnable`, `WExecutorService`)
Expand All @@ -42,13 +40,12 @@
- Thrift-over-HTTP implementation layered on woody-api.
- Client builders (`THClientBuilder`, `THSpawnClientBuilder`,
`THPooledClientBuilder`) construct `TServiceClient`, inject message/transport
interceptors, traceparent propagation, metadata extensions, logging
(`THCEventLogListener`); support custom or pooled HttpClient5.
interceptors, metadata extensions, logging (`THCEventLogListener`); support
custom or pooled HttpClient5.
- Service builder (`THServiceBuilder`) wraps `TProcessor` into `TServlet`,
applies transport interceptors, `THErrorMapProcessor`, logging
(`THSEventLogListener`), and ensures `TraceContext.forService`.
- Extension bundles produce `THCExtensionContext`/`THSExtensionContext`;
`TraceParentUtils` handles W3C traceparent parsing/serialization.
- Extension bundles produce `THCExtensionContext`/`THSExtensionContext`.
- Supplemental packages: `error` (exception ↔ response mapping), `event` (HTTP
logging), `transport` (servlet/client wiring).
- Обновлённый `THProviderErrorMapper` синхронизирует статус, источники ошибок,
Expand All @@ -72,17 +69,13 @@

- `woody-api/src/test`: ID generators, tracing logic, proxy behavior.
- `woody-thrift/src/test`: Jetty quickstart servers + EasyMock cover HTTP
integration, metadata propagation, error mapping, а также свежие
интеграционные сценарии `TraceLifecycleIntegrationTest`, проверяющие
сквозную OpenTelemetry-трассировку (новый/восстановленный контекст,
обработку ошибок, отсутствие обязательных метаданных).
- Дополнительно `THProviderErrorMapperTest` и `MetadataMdcPropagationTest`
контролируют обработку ошибок и перенос MDC/OTel данных.
integration, metadata propagation and error mapping.
- Дополнительно `THProviderErrorMapperTest` контролирует обработку ошибок.

## Key Concepts for Agents

- Always maintain root/service/client span consistency; `TraceContext`
orchestrates init/destroy hooks and ensures MDC/Otel sync.
orchestrates init/destroy hooks and ensures MDC sync.
- Cross-thread execution must wrap tasks with
`WFlow.create`/`createServiceFork`.
- Interceptors are composable; metadata extensions rely on extension bundles
Expand Down Expand Up @@ -122,4 +115,4 @@
- For new metadata, implement `MetadataExtensionKit` and include via builder
`withMetaExtensions`.
- Для фоновых задач используйте `WFlow.createServiceFork(...)` — он создаёт
новый service-span и корректно инициализирует OpenTelemetry контекст.
новый service-span и корректно инициализирует контекст.
2 changes: 1 addition & 1 deletion libthrift/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<artifactId>woody</artifactId>
<groupId>dev.vality.woody</groupId>
<version>2.1.0</version>
<version>3.0.0</version>
</parent>

<artifactId>libthrift</artifactId>
Expand Down
24 changes: 1 addition & 23 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<packaging>pom</packaging>
<groupId>dev.vality.woody</groupId>
<artifactId>woody</artifactId>
<version>2.1.0</version>
<version>3.0.0</version>

<name>Woody Java</name>
<description>Java implementation for Woody spec</description>
Expand Down Expand Up @@ -46,8 +46,6 @@
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<opentelemetry.version>1.49.0</opentelemetry.version>
<opentelemetry-semconv.version>1.37.0</opentelemetry-semconv.version>
</properties>

<modules>
Expand All @@ -68,26 +66,6 @@
<artifactId>slf4j-api</artifactId>
<version>1.7.36</version>
</dependency>
<dependency>
<groupId>io.opentelemetry.semconv</groupId>
<artifactId>opentelemetry-semconv</artifactId>
<version>${opentelemetry-semconv.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
<version>${opentelemetry.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
<version>${opentelemetry.version}</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
<version>${opentelemetry.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
</project>
19 changes: 1 addition & 18 deletions woody-api/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<artifactId>woody</artifactId>
<groupId>dev.vality.woody</groupId>
<version>2.1.0</version>
<version>3.0.0</version>
</parent>

<artifactId>woody-api</artifactId>
Expand Down Expand Up @@ -51,23 +51,6 @@
<artifactId>commons-pool2</artifactId>
<version>2.12.1</version>
</dependency>
<!--Opentelemetry libs-->
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry.semconv</groupId>
<artifactId>opentelemetry-semconv</artifactId>
</dependency>
<!--Test libs-->
<dependency>
<groupId>junit</groupId>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@
import dev.vality.woody.api.trace.ContextSpan;
import dev.vality.woody.api.proxy.tracer.*;
import dev.vality.woody.api.trace.context.TraceContext;
import io.opentelemetry.sdk.resources.Resource;

import java.net.URI;
import java.util.concurrent.atomic.AtomicBoolean;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
import dev.vality.woody.api.proxy.ProxyFactory;
import dev.vality.woody.api.proxy.SingleTargetProvider;
import dev.vality.woody.api.proxy.tracer.*;
import io.opentelemetry.sdk.resources.Resource;

import java.util.concurrent.atomic.AtomicBoolean;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

import dev.vality.woody.api.event.ClientEventListener;
import dev.vality.woody.api.generator.IdGenerator;
import io.opentelemetry.sdk.resources.Resource;

import java.net.URI;

Expand Down
Loading
Loading