Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/expediadotcom/opentracing-spring-haystack-starter
Integration library to enable haystack integration with opentracing-spring-cloud-starter @ https://github.com/opentracing-contrib/java-spring-cloud
https://github.com/expediadotcom/opentracing-spring-haystack-starter
blobs distributed-tracing haystack java opentracing spring
Last synced: about 1 month ago
JSON representation
Integration library to enable haystack integration with opentracing-spring-cloud-starter @ https://github.com/opentracing-contrib/java-spring-cloud
- Host: GitHub
- URL: https://github.com/expediadotcom/opentracing-spring-haystack-starter
- Owner: ExpediaDotCom
- License: apache-2.0
- Created: 2019-02-09T18:53:49.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-10T05:41:51.000Z (about 2 years ago)
- Last Synced: 2023-07-26T21:48:09.805Z (over 1 year ago)
- Topics: blobs, distributed-tracing, haystack, java, opentracing, spring
- Language: Java
- Size: 137 KB
- Stars: 3
- Watchers: 8
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/ExpediaDotCom/opentracing-spring-haystack-starter)
[](https://github.com/ExpediaDotCom/haystack/blob/master/LICENSE)
Table of Contents
=================
* [Table of Contents](#table-of-contents)
* [Instrumenting Spring Boot or Spring Web applications](#instrumenting-spring-boot-or-spring-web-applications)
* [Quick Start](#quick-start)
* [Spring Boot or Spring Web dependency](#spring-boot-or-spring-web-dependency)
* [Spring Application dependency](#spring-application-dependency)
* [Other dependencies](#other-dependencies)
* [Sample yaml/properties file](#sample-yamlproperties-file)
* [Example Project](#example-project)
* [Details](#details)
* [Using this library](#using-this-library)
* [Defaults](#defaults)
* [Configuration](#configuration)
* [Disabling Tracer](#disabling-tracer)
* [Dispatcher(s)](#dispatchers)
* [Logger Dispatcher](#logger-dispatcher)
* [Grpc Agent Dispatcher](#grpc-agent-dispatcher)
* [Http Dispatcher](#http-dispatcher)
* [Dispatcher Bean](#dispatcher-bean)
* [Metrics](#metrics)
* [Customizing Tracer](#customizing-tracer)
* [Deployment](#deployment)
* [Blob Integration](#blob)
## Instrumenting Spring Boot or Spring Web applications
One 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.
These libraries in turn use [opentracing-spring-haystack-starter](opentracing-spring-haystack-starter) which helps build the
`io.opentracing.Tracer` instance required by underlying [io.opentracing.contrib : opentracing-spring-web-starter](https://github.com/opentracing-contrib/java-spring-web).
## Quick Start
This 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
### Spring Boot or Spring Web dependency
Add the following dependency to your application
```xml
com.expedia.www
opentracing-spring-haystack-web-starter
${opentracing-spring-haystack-web-starter.version}
```
Alternately, 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.
```xml
com.expedia.www
opentracing-spring-haystack-cloud-starter
${opentracing-spring-haystack-cloud-starter.version}
```
[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.,
### Spring Application dependency
To access an instance of `opentracing.io.Tracer` to instrument a Spring application, one can add the following dependencies
```xml
com.expedia.www
opentracing-spring-haystack-starter
${opentracing-spring-haystack-starter.version}
```
Enable `@ComponentScan` on the package `com.expedia.haystack.opentracing.spring.starter` to configure the `Tracer` bean
### Other dependencies
Optionally, add the following to get metrics recorded in JMX
```xml
org.springframework.boot
spring-boot-starter-actuator
io.micrometer
micrometer-registry-jmx
${io-micrometer.version}
```
### Sample yaml/properties file
Add 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)
```yaml
spring:
application:
name: springbootsample
opentracing:
haystack:
dispatchers:
logger:
name: span-logger
agent:
enabled: true
host: haystack-agent
port: 35000
```
### Example Project
One can checkout the example project using this integration @ [https://github.com/ExpediaDotCom/opentracing-spring-haystack-example](https://github.com/ExpediaDotCom/opentracing-spring-haystack-example)
## Details
### Using this library
Check maven for latest versions of this library. At present, this library has been built and tested with Spring Boot 2.x
```xml
com.expedia.www
opentracing-spring-haystack-web-starter
${opentracing-spring-haystack-web-starter.version}
```
### Defaults
Adding 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.
* `service-name`: Is read from configuration property `spring.application.name`. If it is not provided then the value will be set to `unnamed-application`
* `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
* `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
### Configuration
One can also configure the tracer created by the library using few configuration properties and optional beans.
#### Disabling Tracer
One can completely disable tracing with configuration property `opentracing.haystack.enabled`. If the property is missing (default), this property value is assumed as `true`.
```yaml
opentracing:
haystack:
enabled: false
```
#### Dispatcher(s)
One can configure `Dispatcher` in two ways: using configuration properties or by creating a spring bean.
Using 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.
##### Logger Dispatcher
One can configure the name of the logger to use in a LoggerDispatcher by setting the following property in Spring Boot yaml or properties file
```yaml
opentracing:
haystack:
dispatchers:
logger:
name: span-logger
```
##### Grpc Agent Dispatcher
Haystack 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.
```yaml
opentracing:
haystack:
dispatchers:
agent:
enabled: true
```
There are other properties available to further configure the grpc agent dispatcher
```properties
opentracing.haystack.dispatchers.agent.host=haystack-agent
opentracing.haystack.dispatchers.agent.port=35000
opentracing.haystack.dispatchers.agent.keep-alive-time-m-s=30
opentracing.haystack.dispatchers.agent.keep-alive-timeout-m-s=30
opentracing.haystack.dispatchers.agent.keep-alive-without-calls=true
opentracing.haystack.dispatchers.agent.negotiation-type=PLAINTEXT
```
Alternately, 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).
```java
public interface GrpcDispatcherFactory {
Dispatcher create(MetricsRegistry metricsRegistry,
TracerSettings.AgentConfiguration agentConfiguration);
}
```
If available, this bean will be invoked with configuration properties defined to build a RemoteDispatcher with GrpcAgentClient.
```java
@Bean
public GrpcDispatcherFactory grpcDispatcherFactory() {
return (metricsRegistry, config) ->
new RemoteDispatcher.Builder(metricsRegistry,
config.builder(metricsRegistry).build()).build();
}
```
##### Http Dispatcher
Haystack also provides a [http collector](https://github.com/ExpediaDotCom/haystack-collector/tree/master/http) to ingest Json and Protobuf serialized spans over http.
One can configure a http dispatcher by adding the following endpoint configuration
```yaml
opentracing:
haystack:
dispatchers:
http:
endpoint: http://localhost:8080/span
headers:
client-id: foo
client-key: bar
```
`headers` property is optional. All properties defined under 'headers' will be sent as HTTP headers along with the serialized span data.
As 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
##### Dispatcher Bean
Instead 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).
#### Metrics
As 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.
For example, adding the following two dependencies to the application will automatically create a `MeterRegistry` bean and write the metrics to JMX
```xml
org.springframework.boot
spring-boot-starter-actuator
io.micrometer
micrometer-registry-jmx
${io-micrometer.version}
```
#### Customizing Tracer
Haystack 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).
## Deployment
Update the version of repo using:
```
./mvnw org.codehaus.mojo:versions-maven-plugin:2.5:set -DnewVersion=-SNAPSHOT
```
Please don't remove snapshot from the version. The travis job is triggered when a new PR is merged in the master branch.
Travis also updates the project version whenever a new release is tagged.
## Blob
One 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.
For 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.
```yaml
haystack:
blobs:
enabled: true
store:
name: file # for local development
```
To use haystack-agent, use following:
```yaml
haystack:
blobs:
enabled: true
store:
name: agent
host: haystack-agent
port: 35001
```
If 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.
For 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.
Please note, the blobs integration works both for client and server side span.