{"id":20337312,"url":"https://github.com/expediadotcom/opentracing-spring-haystack-starter","last_synced_at":"2025-04-11T22:41:53.277Z","repository":{"id":34188160,"uuid":"169901539","full_name":"ExpediaDotCom/opentracing-spring-haystack-starter","owner":"ExpediaDotCom","description":"Integration library to enable haystack integration with opentracing-spring-cloud-starter  @ https://github.com/opentracing-contrib/java-spring-cloud","archived":false,"fork":false,"pushed_at":"2022-12-10T05:41:51.000Z","size":140,"stargazers_count":3,"open_issues_count":2,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-25T18:45:07.700Z","etag":null,"topics":["blobs","distributed-tracing","haystack","java","opentracing","spring"],"latest_commit_sha":null,"homepage":null,"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/ExpediaDotCom.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}},"created_at":"2019-02-09T18:53:49.000Z","updated_at":"2020-01-28T10:19:46.000Z","dependencies_parsed_at":"2023-01-15T05:10:15.563Z","dependency_job_id":null,"html_url":"https://github.com/ExpediaDotCom/opentracing-spring-haystack-starter","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpediaDotCom%2Fopentracing-spring-haystack-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpediaDotCom%2Fopentracing-spring-haystack-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpediaDotCom%2Fopentracing-spring-haystack-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpediaDotCom%2Fopentracing-spring-haystack-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ExpediaDotCom","download_url":"https://codeload.github.com/ExpediaDotCom/opentracing-spring-haystack-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248493022,"owners_count":21113159,"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":["blobs","distributed-tracing","haystack","java","opentracing","spring"],"created_at":"2024-11-14T21:08:36.179Z","updated_at":"2025-04-11T22:41:53.223Z","avatar_url":"https://github.com/ExpediaDotCom.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/ExpediaDotCom/opentracing-spring-haystack-starter.svg?branch=master)](https://travis-ci.org/ExpediaDotCom/opentracing-spring-haystack-starter)\r\n[![License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg)](https://github.com/ExpediaDotCom/haystack/blob/master/LICENSE)\r\n\r\nTable of Contents\r\n=================\r\n\r\n* [Table of Contents](#table-of-contents)\r\n   * [Instrumenting Spring Boot or Spring Web applications](#instrumenting-spring-boot-or-spring-web-applications)\r\n   * [Quick Start](#quick-start)\r\n      * [Spring Boot or Spring Web dependency](#spring-boot-or-spring-web-dependency)\r\n      * [Spring Application dependency](#spring-application-dependency)\r\n      * [Other dependencies](#other-dependencies)\r\n      * [Sample yaml/properties file](#sample-yamlproperties-file)\r\n      * [Example Project](#example-project)\r\n   * [Details](#details)\r\n      * [Using this library](#using-this-library)\r\n      * [Defaults](#defaults)\r\n      * [Configuration](#configuration)\r\n         * [Disabling Tracer](#disabling-tracer)\r\n         * [Dispatcher(s)](#dispatchers)\r\n            * [Logger Dispatcher](#logger-dispatcher)\r\n            * [Grpc Agent Dispatcher](#grpc-agent-dispatcher)\r\n            * [Http Dispatcher](#http-dispatcher)\r\n            * [Dispatcher Bean](#dispatcher-bean)\r\n         * [Metrics](#metrics)\r\n         * [Customizing Tracer](#customizing-tracer)\r\n   * [Deployment](#deployment)\r\n   * [Blob Integration](#blob)\r\n\r\n\r\n## Instrumenting Spring Boot or Spring Web applications\r\n\r\nOne can use [opentracing-spring-haystack-web-starter](opentracing-spring-haystack-web-starter) or [opentracing-spring-haystack-cloud-starter](opentracing-spring-haystack-cloud-starter) to instrument spring boot or spring web applications and send tracing information to Opentracing complicant [Haystack](https://expediadotcom.github.io/haystack/) server, distributed tracing platform. \r\n\r\nThese libraries in turn use [opentracing-spring-haystack-starter](opentracing-spring-haystack-starter) which helps build the \r\n`io.opentracing.Tracer` instance required by underlying [io.opentracing.contrib : opentracing-spring-web-starter](https://github.com/opentracing-contrib/java-spring-web). \r\n\r\n## Quick Start\r\n\r\nThis section provides steps required to quickly configure your spring application to be wired using Opentracing's spring integration to Haystack. If you need additional information, please read the subsequent sections in this documentation\r\n\r\n### Spring Boot or Spring Web dependency\r\n\r\nAdd the following dependency to your application\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.expedia.www\u003c/groupId\u003e\r\n    \u003cartifactId\u003eopentracing-spring-haystack-web-starter\u003c/artifactId\u003e\r\n    \u003cversion\u003e${opentracing-spring-haystack-web-starter.version}\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\nAlternately, one can use `opentracing-spring-haystack-cloud-starter` instead. It is convenience starter that includes opentracing-spring-haystack-starter, opentracing-spring-web-starter and opentracing-spring-cloud-starter. This allows one to take advantage of opentracing instrumentation provided for Spring Cloud.\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.expedia.www\u003c/groupId\u003e\r\n    \u003cartifactId\u003eopentracing-spring-haystack-cloud-starter\u003c/artifactId\u003e\r\n    \u003cversion\u003e${opentracing-spring-haystack-cloud-starter.version}\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n[opentracing-spring-cloud-starter](https://github.com/opentracing-contrib/java-spring-cloud#opentracing-spring-cloud) provides ready instrumentation of various known OSS projects like Redis, Hystrix etc.,\r\n\r\n### Spring Application dependency\r\n\r\nTo access an instance of `opentracing.io.Tracer` to instrument a Spring application, one can add the following dependencies\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.expedia.www\u003c/groupId\u003e\r\n    \u003cartifactId\u003eopentracing-spring-haystack-starter\u003c/artifactId\u003e\r\n    \u003cversion\u003e${opentracing-spring-haystack-starter.version}\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\nEnable `@ComponentScan` on the package `com.expedia.haystack.opentracing.spring.starter` to configure the `Tracer` bean\r\n\r\n### Other dependencies\r\n\r\nOptionally, add the following to get metrics recorded in JMX\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\r\n    \u003cartifactId\u003espring-boot-starter-actuator\u003c/artifactId\u003e\r\n\u003c/dependency\u003e\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003eio.micrometer\u003c/groupId\u003e\r\n    \u003cartifactId\u003emicrometer-registry-jmx\u003c/artifactId\u003e\r\n    \u003cversion\u003e${io-micrometer.version}\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n### Sample yaml/properties file\r\n\r\nAdd the following to the properties or yaml file of the application being instrumented  (this is just a sample. change the name of the application, host name/port of the agent etc)\r\n\r\n```yaml\r\nspring:\r\n  application:\r\n    name: springbootsample\r\n    \r\nopentracing:\r\n  haystack:\r\n    dispatchers:\r\n      logger:\r\n        name: span-logger\r\n      agent:\r\n        enabled: true\r\n        host: haystack-agent\r\n        port: 35000\r\n```\r\n\r\n### Example Project\r\n\r\nOne can checkout the example project using this integration @ [https://github.com/ExpediaDotCom/opentracing-spring-haystack-example](https://github.com/ExpediaDotCom/opentracing-spring-haystack-example) \r\n\r\n## Details\r\n\r\n### Using this library\r\n\r\nCheck maven for latest versions of this library. At present, this library has been built and tested with Spring Boot 2.x\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.expedia.www\u003c/groupId\u003e\r\n    \u003cartifactId\u003eopentracing-spring-haystack-web-starter\u003c/artifactId\u003e\r\n    \u003cversion\u003e${opentracing-spring-haystack-web-starter.version}\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n### Defaults\r\n\r\nAdding this library autoconfigures an instance of [Haystack Tracer](https://github.com/ExpediaDotCom/haystack-client-java/blob/opentracing-spring-haystack-starter/core/src/main/java/com/expedia/www/haystack/client/Tracer.java) using defaults mentioned below. \r\n\r\n* `service-name`: Is read from configuration property `spring.application.name`. If it is not provided then the value will be set to `unnamed-application`\r\n* `dispatcher`: Spans are dispatched to Haystack using one or more [Dispatcher](https://github.com/ExpediaDotCom/haystack-client-java/blob/master/core/src/main/java/com/expedia/www/haystack/client/dispatchers/Dispatcher.java) instances. If none is configured or created, then a [LoggerDispatcher](https://github.com/ExpediaDotCom/haystack-client-java/blob/master/core/src/main/java/com/expedia/www/haystack/client/dispatchers/LoggerDispatcher.java) is configured with \"haystack\" as the logger name\r\n* `metrics`: This library depends on Micrometer's MeterRegistry to instrument the library itself. If no instance of `MeterRegistry` is present in the [spring application](https://spring.io/blog/2018/03/16/micrometer-spring-boot-2-s-new-application-metrics-collector#what-do-i-get-out-of-the-box), then it uses a built-in No-op implementation. Which means no metrics are recorded\r\n\r\n### Configuration\r\n\r\nOne can also configure the tracer created by the library using few configuration properties and optional beans.\r\n\r\n#### Disabling Tracer\r\n\r\nOne can completely disable tracing with configuration property `opentracing.haystack.enabled`. If the property is missing (default), this property value is assumed as `true`.\r\n\r\n```yaml\r\nopentracing:\r\n  haystack:\r\n    enabled: false\r\n```\r\n\r\n#### Dispatcher(s)\r\n\r\nOne can configure `Dispatcher` in two ways: using configuration properties or by creating a spring bean.\r\n\r\nUsing configuration properties one can configure one or more of the following dispatchers. Configuring more than one dispatcher, creates a `ChainedDispatcher` and sends a span to all of the configured dispatcher instances.\r\n\r\n##### Logger Dispatcher\r\n\r\nOne can configure the name of the logger to use in a LoggerDispatcher by setting the following property in Spring Boot yaml or properties file\r\n\r\n```yaml\r\nopentracing:\r\n  haystack:\r\n    dispatchers:\r\n      logger:\r\n        name: span-logger\r\n```\r\n\r\n##### Grpc Agent Dispatcher\r\n\r\nHaystack provides a [GRPC agent](https://github.com/ExpediaDotCom/haystack-agent) as a convenience to send protobuf spans to Haystack's kafka. One can configure grpc agent by simply enabling it in the configuration. \r\n\r\n```yaml\r\nopentracing:\r\n  haystack:\r\n    dispatchers:\r\n      agent:\r\n        enabled: true\r\n```\r\n\r\nThere are other properties available to further configure the grpc agent dispatcher\r\n\r\n```properties\r\nopentracing.haystack.dispatchers.agent.host=haystack-agent\r\nopentracing.haystack.dispatchers.agent.port=35000\r\nopentracing.haystack.dispatchers.agent.keep-alive-time-m-s=30\r\nopentracing.haystack.dispatchers.agent.keep-alive-timeout-m-s=30\r\nopentracing.haystack.dispatchers.agent.keep-alive-without-calls=true\r\nopentracing.haystack.dispatchers.agent.negotiation-type=PLAINTEXT\r\n```\r\n\r\nAlternately, one can create a bean of type [GrpcDispatcherFactory](https://github.com/ExpediaDotCom/opentracing-spring-haystack-starter/blob/master/opentracing-spring-haystack-starter/src/main/java/com/expedia/haystack/opentracing/spring/starter/support/GrpcDispatcherFactory.java). \r\n\r\n```java\r\npublic interface GrpcDispatcherFactory {\r\n    Dispatcher create(MetricsRegistry metricsRegistry, \r\n                      TracerSettings.AgentConfiguration agentConfiguration);\r\n}\r\n```\r\n\r\nIf available, this bean will be invoked with configuration properties defined to build a RemoteDispatcher with GrpcAgentClient.\r\n\r\n```java\r\n@Bean\r\npublic GrpcDispatcherFactory grpcDispatcherFactory() {\r\n    return (metricsRegistry, config) -\u003e\r\n            new RemoteDispatcher.Builder(metricsRegistry, \r\n                                         config.builder(metricsRegistry).build()).build();\r\n}\r\n```\r\n\r\n##### Http Dispatcher\r\n\r\nHaystack also provides a [http collector](https://github.com/ExpediaDotCom/haystack-collector/tree/master/http) to ingest Json and Protobuf serialized spans over http.\r\n\r\nOne can configure a http dispatcher by adding the following endpoint configuration\r\n\r\n```yaml\r\nopentracing:\r\n  haystack:\r\n    dispatchers:\r\n      http:\r\n        endpoint: http://localhost:8080/span\r\n        headers: \r\n          client-id: foo\r\n          client-key: bar\r\n```\r\n\r\n`headers` property is optional. All properties defined under 'headers' will be sent as HTTP headers along with the serialized span data. \r\n\r\nAs in Grpc Agent, one can create a bean of type [HttpDispatcherFactory](https://github.com/ExpediaDotCom/opentracing-spring-haystack-starter/blob/master/opentracing-spring-haystack-starter/src/main/java/com/expedia/haystack/opentracing/spring/starter/support/HttpDispatcherFactory.java). If available, that bean will be invoked to create a RemoteDispatcher with HttpClient\r\n\r\n##### Dispatcher Bean\r\n\r\nInstead of configuring dispatchers through properties, one can create a bean of type `Dispatcher` in the application's spring context. This library will use that bean instead of creating one using configuration or defaults. One can see this in the [integration test example](opentracing-spring-haystack-web-starter/src/test/java/com/expedia/haystack/opentracing/spring/starter/DispatcherInjectionIntegrationTest.java#L57).\r\n\r\n#### Metrics\r\n\r\nAs mentioned earlier, this library looks for a bean of type [Micrometer's MeterRegistry](https://micromerter.io). If present, it uses that to write all metrics from the library to the configured store. If not, the library will use a no-op implementation and no metrics will be written.\r\n\r\nFor example, adding the following two dependencies to the application will automatically create a `MeterRegistry` bean and write the metrics to JMX\r\n\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\r\n    \u003cartifactId\u003espring-boot-starter-actuator\u003c/artifactId\u003e\r\n\u003c/dependency\u003e\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003eio.micrometer\u003c/groupId\u003e\r\n    \u003cartifactId\u003emicrometer-registry-jmx\u003c/artifactId\u003e\r\n    \u003cversion\u003e${io-micrometer.version}\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n#### Customizing Tracer\r\n\r\nHaystack Tracer's [Builder](https://github.com/ExpediaDotCom/haystack-client-java/blob/master/core/src/main/java/com/expedia/www/haystack/client/Tracer.java#L356) class exposes a number of possible configurations that can be used to customize the `Tracer` instance built by this library and used by [Opentracing's Spring integration](https://github.com/opentracing-contrib/java-spring-web/). To customize the Tracer instance, one can create a bean of type [TracerCustomizer](opentracing-spring-haystack-starter/src/main/java/com/expedia/haystack/opentracing/spring/starter/support/TracerCustomizer.java). This will be invoked when the library attempts to build an instance of Tracer. One can see this in the [integration test](opentracing-spring-haystack-web-starter/src/test/java/com/expedia/haystack/opentracing/spring/starter/TracerCustomizerIntegrationTest.java#L29).\r\n\r\n## Deployment\r\n\r\nUpdate the version of repo using: \r\n```\r\n./mvnw org.codehaus.mojo:versions-maven-plugin:2.5:set -DnewVersion=\u003cversion\u003e-SNAPSHOT\r\n```\r\nPlease don't remove snapshot from the version. The travis job is triggered when a new PR is merged in the master branch.\r\nTravis also updates the project version whenever a new release is tagged.\r\n\r\n\r\n## Blob\r\nOne can turn on the blob feature that writes the request+response payload in distributed file-system and also adds a span tag to dereference the store location. \r\nFor more information, read [here](https://github.com/ExpediaDotCom/blobs). One can also use [haystack-agent](https://github.com/ExpediaDotCom/haystack-agent) as a blob forwarder to distributed file systems like AWS/S3.\r\n\r\n```yaml\r\nhaystack:\r\n  blobs:\r\n   enabled: true\r\n   store:\r\n    name: file # for local development\r\n```\r\n\r\nTo use haystack-agent, use following:\r\n\r\n```yaml\r\nhaystack:\r\n  blobs:\r\n   enabled: true\r\n   store:\r\n    name: agent\r\n    host: haystack-agent\r\n    port: 35001\r\n```\r\n\r\nIf one wants to blob conditionally based on certain properties on request/response, then one needs to implement the [Blobable](./haystack-spring-blobs-starter/src/main/java/com/expedia/haystack/blobs/spring/starter/Blobable.java) interface. \r\nFor instance, one can control to blob only if there is a http failure. Check the [BlobStoreTest](./opentracing-spring-haystack-web-starter/src/test/java/com/expedia/haystack/opentracing/spring/starter/BlobStoreTest.java) example for quick reference. \r\nPlease note, the blobs integration works both for client and server side span. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpediadotcom%2Fopentracing-spring-haystack-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexpediadotcom%2Fopentracing-spring-haystack-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpediadotcom%2Fopentracing-spring-haystack-starter/lists"}