{"id":21153003,"url":"https://github.com/opentracing-contrib/java-jaxrs","last_synced_at":"2025-04-05T06:06:38.030Z","repository":{"id":47048832,"uuid":"76054612","full_name":"opentracing-contrib/java-jaxrs","owner":"opentracing-contrib","description":"OpenTracing Java JAX-RS instrumentation","archived":false,"fork":false,"pushed_at":"2023-12-16T17:21:15.000Z","size":409,"stargazers_count":37,"open_issues_count":25,"forks_count":33,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-29T05:04:56.265Z","etag":null,"topics":["apache-cxf","instrumentation","jax-rs","jaxrs","jersey","opentracing","resteasy","tracing"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opentracing-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-09T17:07:10.000Z","updated_at":"2024-05-17T16:45:31.000Z","dependencies_parsed_at":"2024-11-20T11:23:24.972Z","dependency_job_id":"d3101359-7546-4499-b421-f5e6d134c6b4","html_url":"https://github.com/opentracing-contrib/java-jaxrs","commit_stats":null,"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-jaxrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-jaxrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-jaxrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-jaxrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opentracing-contrib","download_url":"https://codeload.github.com/opentracing-contrib/java-jaxrs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294536,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache-cxf","instrumentation","jax-rs","jaxrs","jersey","opentracing","resteasy","tracing"],"created_at":"2024-11-20T10:48:00.620Z","updated_at":"2025-04-05T06:06:38.010Z","avatar_url":"https://github.com/opentracing-contrib.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status][ci-img]][ci] [![Released Version][maven-img]][maven]\n\n# OpenTracing JAX-RS Instrumentation\n\nOpenTracing instrumentation for JAX-RS standard. It supports tracing of server and client requests.\n\nInstrumentation by default adds a set of standard HTTP tags and as an operation name it uses a string defined in `@Path` annotation.\nCustom tags or operation name can be added via span decorators.\nThis instrumentation also supports tracing of (de)serialization of response and requests bodies.\n\n## MicroProfile-OpenTracing\nThis implementation is compatible with [MicroProfile-OpenTracing (MP-OT)](https://github.com/eclipse/microprofile-opentracing).\nIt can be used as a building block of MicroProfile compatible application server. Note that\napplication servers have to add a few things which are not provided by this project: CDI interceptor, \nautomatically register tracing filters into client... [SmallRye-OpenTracing](https://github.com/smallrye/smallrye-opentracing)\nuses this library to provide a vendor neutral implementation of MP-OT.\n\n## Tracing server requests\nTracing server requests requires two components: JAX-RS dynamic feature and servlet filter.\nSpan is started in JAX-RS filter and finished in servlet filter.\n\n## Auto discovery\nTracing can be automatically enabled by adding the following dependency on classpath.\nThis mechanism requires a tracer to be registered in `GlobalTracer`. This is typically done in\n`ServletContextListener`. Note that JAX-RS clients are not automatically instrumented. Client tracing\nfeature has to be explicitly registered to all client instances.\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.opentracing.contrib\u003c/groupId\u003e\n  \u003cartifactId\u003eopentracing-jaxrs2-discovery\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\n### Custom configuration\nFor custom configuration use the following dependency:\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.opentracing.contrib\u003c/groupId\u003e\n  \u003cartifactId\u003eopentracing-jaxrs2\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\nThe Custom configuration can be achieved by adding `ServerTracingDynamicFeature` to `Application.singletons` or by wrapping the feature with a class annotated with `@Provider`. \nThis approach does not require adding all classes to singletons set.\n\nDynamic feature registration via custom provider:\n```java\n@Provider\npublic class TracingInitializer implements DynamicFeature {\n\n  private final ServerTracingDynamicFeature serverTracingDynamicFeature =\n      new ServerTracingDynamicFeature.Builder(GlobalTracer.get())\n          .withOperationNameProvider(ClassNameOperationName.newBuilder())\n      .build();\n\n  @Override\n  public void configure(ResourceInfo resourceInfo, FeatureContext context) {\n    serverTracingDynamicFeature.configure(resourceInfo, context);\n  }\n}\n\n```\n\nDynamic feature registration via singletons:\n```java\npublic class JaxRsApp extends javax.ws.rs.core.Application {\n\n  @Override\n  public Set\u003cObject\u003e getSingletons() {\n    DynamicFeature tracing = new ServerTracingDynamicFeature.Builder(tracer)\n        .withDecorators(decorators)\n        .withSerializationDecorators(serializationDecorators)\n        .build();\n\n    return Collections.singleton(tracing);\n  }\n}\n```\n\nFilter registration:\n```java\n@WebListener\npublic class OpenTracingContextInitializer implements javax.servlet.ServletContextListener {\n\n  @Override\n  public void contextInitialized(ServletContextEvent servletContextEvent) {\n    io.opentracing.tracer tracer = new ....\n    GlobalTracer.register(tracer); // or preferably use CDI\n    \n    ServletContext servletContext = servletContextEvent.getServletContext();\n    Dynamic filterRegistration = servletContext\n        .addFilter(\"tracingFilter\", new SpanFinishingFilter());\n    filterRegistration.setAsyncSupported(true);\n    filterRegistration.addMappingForUrlPatterns(EnumSet.of(DispatcherType.REQUEST, DispatcherType.ASYNC), false, \"*\");\n  }\n}\n```\n\nAn example of traced REST endpoint:\n```java\n@GET\n@Path(\"/hello\")\n@Traced(operationName = \"helloRenamed\") // optional, see javadoc\npublic Response hello() { // optional to get server span context\n\n  // this span will be ChildOf of span representing server request processing\n  Span childSpan = tracer.buildSpan(\"businessOperation\")\n          .start())\n\n   // business logic\n  childSpan.finish();\n\n  return Response.status(Response.Status.OK).build();\n}\n```\n\n## Tracing client requests\n```java\nClient client = ClientBuilder.newBuilder()\n  .reqister(ClientTracingFeature.class)\n  .build();\n\nResponse response = client.target(\"http://localhost/endpoint\")\n  .request()\n  .property(TracingProperties.CHILD_OF, parentSpanContext) // optional, by default new parent is inferred from span source\n  .property(TracingProperties.TRACING_DISABLED, false) // optional, by default everything is traced\n  .get();\n```\n\n### Async\nAsync requests are executed in a different thread than when the client has been invoked, therefore\nspans representing client requests are not connected to appropriate parent. To fix this JAX-RS client\nhas to use OpenTracing-aware [`ExecutorService`](https://github.com/opentracing-contrib/java-concurrent).\n\n#### Jersey\n```java\n@ClientAsyncExecutor\npublic class DelegateExecutorServiceProvider implements ExecutorServiceProvider {\n\n  private final ExecutorService executorService;\n\n  public DelegateExecutorServiceProvider(ExecutorService executorService) {\n    this.executorService = executorService;\n  }\n\n  @Override\n  public ExecutorService getExecutorService() {\n    return executorService;\n  }\n\n  @Override\n  public void dispose(ExecutorService executorService) {\n  }\n}\n\nClient client = ClientBuilder.newBuilder()\n    .register(new DelegateExecutorServiceProvider(\n        new TracedExecutorService(Executors.newFixedThreadPool(8), tracer)))\n    ...\n```\n\n#### RestEasy\n```java\nClient client = new ResteasyClientBuilder()\n    .executorService(new TracedExecutorService(Executors.newFixedThreadPool(8), tracer))\n    ...\n```\n\n## Development\n```shell\n./mvnw clean install\n```\n\n## Release\nFollow instructions in [RELEASE](RELEASE.md)\n\n   [ci-img]: https://travis-ci.org/opentracing-contrib/java-jaxrs.svg?branch=master\n   [ci]: https://travis-ci.org/opentracing-contrib/java-jaxrs\n   [maven-img]: https://img.shields.io/maven-central/v/io.opentracing.contrib/opentracing-jaxrs2.svg?maxAge=2592000\n   [maven]: http://search.maven.org/#search%7Cga%7C1%7Copentracing-jaxrs2\n   \n   ## License\n\n[Apache 2.0 License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopentracing-contrib%2Fjava-jaxrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopentracing-contrib%2Fjava-jaxrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopentracing-contrib%2Fjava-jaxrs/lists"}