Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chonton/apm-client
Java client for DataDog APM
https://github.com/chonton/apm-client
datadog-apm distributed distributed-trace java trace up-for-adoption
Last synced: 2 months ago
JSON representation
Java client for DataDog APM
- Host: GitHub
- URL: https://github.com/chonton/apm-client
- Owner: chonton
- License: apache-2.0
- Created: 2017-01-02T03:50:51.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-03-21T21:35:49.000Z (9 months ago)
- Last Synced: 2024-10-02T10:08:10.482Z (3 months ago)
- Topics: datadog-apm, distributed, distributed-trace, java, trace, up-for-adoption
- Language: Java
- Homepage:
- Size: 1.14 MB
- Stars: 12
- Watchers: 4
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# UP FOR ADOPTION
# apm-client
This java client intercepts servlet requests, jax-rs client requests, and bean methods. The resource
and method names as well as the wall time and duration of the request are recorded in spans. These
spans are queued and sent as REST messages to a [Datadog APM collector](https://www.datadoghq.com/apm/).
[Javadoc](https://chonton.github.io/apm-client/0.0.8/client/apidocs/index.html) and [build reports](https://chonton.github.io/apm-client/0.0.8/client/project-reports.html) are available.
### Requirements
* Minimal latency in the mainline processing
* Some, but not extreme, buffering of outgoing messages
* Thread-safe sender
* Lack of APM collector will be logged, but not cause failure of mainline processing
### Assumptions
* Minimum of Java 8
* Local (on the same host) APM collector
* [CDI](http://www.cdi-spec.org/) implementation such as [Weld](http://weld.cdi-spec.org/)
* [Slf4J](https://www.slf4j.org/) compliant logging implementation such as [Logback](http://logback.qos.ch/)
* [Jax-Rs](https://jax-rs-spec.java.net/) client for optional support of exporting traces
## Maven Coordinates
To include apm-client in your maven build, use the following fragment in your pom.
```xml
org.honton.chas.datadog.apm
client
0.0.8
```
## Configuration
To configure apm-client, you must supply a CDI factory method which produces a TraceConfiguration
instance. Three attributes are configured:
* The service name reported with each span sent to Datadog APM collector.
* The URL of the local Datadog APM collector. If null or empty, this will prevent sending traces.
* The number of milliseconds to backoff.
After any communication failure, the apm-client logs the failure and will not further attempt to
send span information for the backoff period. During this period all spans are dropped.
```java
public class TraceConfigurationFactory {
/**
* Get the configuration.
* @return The configuration
*/
@Produces
static TraceConfiguration getDefault() {
return new TraceConfiguration(
"service-name", // service name
"http://localhost:8126", // apm collector url
TimeUnit.MINUTES.toMillis(1)); // backoff period
}
}
```
## Servlet or Container Filter
On the server side, you can either use TraceServletFilter or TraceContainerFilter to trace incoming requests.
TraceServletFilter can trace any servlet request and annotates the trace with the incoming URI.
TraceContainerFilter can trace any jax-rs request and annotates the trace with the serving class and method.
## TraceServletFilter
The TraceServletFilter traces every incoming request. The http request host/port is
reported as the trace resource and the http request method and url are reported as the trace name.
If the client request includes the
**x-ddtrace-parent_trace_id** and **x-ddtrace-parent_span_id** headers, that indicated span is used as
the parent trace and span. Otherwise, a new trace is created. Once the request is complete, the
new span or trace is closed and sent to Datadog APM.
### Registration in War
Register TraceServletFilter, weld, and Jax-Rs application in the web.xml:
```xml
org.honton.chas.datadog.apm.servlet.TraceServletFilter
org.jboss.weld.environment.servlet.Listener
org.glassfish.jersey.servlet.ServletContainer
javax.ws.rs.Application
org.honton.chas.datadog.apm.example.server.HelloApplication
```
### or Registration with embedded Jetty
```java
public HelloMain(int port) {
this.port = port;
context = new ServletContextHandler();
context.setContextPath("/");
// Use Weld to inject into servlets
context.addEventListener(new org.jboss.weld.environment.servlet.Listener());
// Add the Tracing Filter
context.addFilter(TraceServletFilter.class, "/*", EnumSet.of(DispatcherType.REQUEST));
jettyServer = new Server(port);
jettyServer.setHandler(context);
addJaxRsApplication(HelloApplication.class);
start();
}
```
## TraceContainerFilter
The TraceContainerFilter traces every incoming jax-rs request. The implementation class and method are
reported as the trace resource and name. If the client request includes the
**x-ddtrace-parent_trace_id** and **x-ddtrace-parent_span_id** headers, that indicated span is used as
the parent trace and span. Otherwise, a new trace is created. Once the request is complete, the
new span or trace is closed and sent to Datadog APM.
### Registration
The TraceContainerFilter must be registered with the jax-rs runtime. This can be done during startup as
part of the Application class.
```java
@ApplicationPath("/")
public class HellloApplication extends Application {
@Override
public Set> getClasses() {
Set> classes = new HashSet<>();
// Register the service endpoint
classes.add(HelloService.class);
// the Tracing filter
classes.add(TraceContainerFilter.class);
return classes;
}
}
```
## TraceClientFilter
TraceClientFilter exports outgoing requests. Prior to sending the request, a new span is created.
The outgoing requests includes **x-ddtrace-parent_trace_id** and **x-ddtrace-parent_span_id** headers
indicating that new span. Once the request has completed, the span is closed and sent to Datadog APM.
```java
public class ClientProxyFactory {
private ResteasyClientBuilder clientBuilder;
@Inject
void setTraceFilter(TraceClientFilter filter) {
clientBuilder = new ResteasyClientBuilder();
clientBuilder.register(filter);
}
public T getProxy(String url, Class cls) {
return clientBuilder.build().target(url).proxy(cls);
}
}
```
## TraceInterceptor
The TraceOperation annotation instructs TraceInterceptor to create a new span is before entering a
CDI bean operation and close the span once the operation is complete. Completed spans are sent to
Datadog APM. The TraceOperation annotation can be placed on the class or the method definition.
Placing the annotation on a method will cause any invocation from outside the class to be traced.
Placing the annotation on a class will cause all methods in that class to be traced, unless the
method is annotated with **@TraceOperation(false)**.
```java
@TraceOperation(type=TraceOperation.DB)
public class ExampleBean {
/**
* Trace turned on at class level
*/
public void methodToTrace() {
// ...
}
/**
* Trace turned off at method level
*/
@TraceOperation(false)
public void dontTrace() {
// ...
}
}
```
## TraceProxyFactory
Occasionally, you will need to intercept operations on non-cdi instances. In this case, you can
create a proxy which will create a new span before invoking any interface method and close the span
once the invocation is complete.
```java
public class BeanFactory {
@Inject
TraceProxyFactory proxyFactory;
@Produces
public NonCdi factoryMethod() {
return proxyFactory.createProxy(new NonCdiImpl(), NonCdi.class);
}
}
```
## Tracer
Similarly, application code can use the Tracer create a new span is before entering a Callable or
Runnable and close the spans once the calls are complete. Completed spans are immediately
queued to send to Datadog APM. Inject the Tracer to report spans with application code.
```java
@Inject
private Tracer tracer;
public String someMethod() {
return tracer.executeCallable("resource", "operation", () -> {
// code to run inside span
return "returnValue";
});
}
```
# Update Notes
## 0.0.7 to 0.0.8
Update jackson dependency
## 0.0.6 to 0.0.7
Update jackson dependency
## 0.0.5 to 0.0.6
The URL of the local Datadog APM collector can be set to null or empty; this will prevent sending traces.
## 0.0.4 to 0.0.5
An incompatible change was made in the encoding of numbers in the trace and span headers. Prior to
0.0.5, the numbers were encoded in hexadecimal. From 0.0.5 onwards the encoding is in decimal. Additionally,
prior to version 0.0.5, the parsing of header did not handle invalid numbers. To upgrade without downtime,
rebuild and deploy the more dependent services first.