open-telemetry
/
opentelemetry-java-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-java-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
opentelemetry-java-instrume.../dd-java-agent/README.md

7.9 KiB
Raw Blame History

Datadog Java Agent for APM

Minimal Java version required: 1.7

This is a Java Agent to instrument Java applications using the Datadog Tracer. Once attached to one of your JVM you should see traces in Datadog APM.

Tracing instrumentation can be done in 2 ways:

❗ Warning: This library is currently in Alpha. This means that even though we rigorously tested instrumentations you may experience strange behaviors depending on your running environment. Be sure to test thoroughly on a staging environment before releasing to production. For any help please contact tracehelp@datadoghq.com.

Quick start

1. Install the Datadog Agent on your OS

The Java instrumentation library works in collaboration with a local agent that transmits the traces to Datadog. To install it with tracing please follow these steps:

[Main]
# Enable the trace agent.
apm_enabled: true

2. Instrument your application

To instrument your project or your servers you simply have to declare the provided jar file in your JVM arguments as a valid -javaagent:.

  • So first download the jar file from the main repository.
# use latest version 
curl -OL http://central.maven.org/maven2/com/datadoghq/dd-java-agent/{version}/dd-java-agent-{version}.jar
  • Then add the following JVM argument when launching your application (in IDE, using Maven run or simply in collaboration with the >java -jar command):
-javaagent:/path/to/the/dd-java-agent-{version}.jar

That's it! If you did this properly the agent was executed at pre-main, had detected and instrumented the supported libraries and custom traces. You should then see traces on Datadog APM.

Configuration

Configuration is done through a default dd-trace.yaml file as a resource in the classpath. You can also override it by adding the file path as a system property when launching the JVM: -Ddd.trace.configurationFile.

# Main service name for the app
defaultServiceName: java-app

# The writer to use.
# Could be: LoggingWritter or DDAgentWriter (default)
writer:
  # LoggingWriter: Spans are logged using the application configuration
  # DDAgentWriter: Spans are forwarding to a Datadog Agent
  #  - Param 'host': the hostname where the DD Agent running (default: localhost)
  #  - Param 'port': the port to reach the DD Agent (default: 8126)
  type: DDAgentWriter
  host: localhost
  port: 8126

# The sampler to use.
# Could be: AllSampler (default) or RateSampler
sampler:
  # AllSampler: all spans are reported to the writer
  # RateSample: only a portion of spans are reported to the writer
  #  - Param 'rate': the portion of spans to keep
  type: AllSampler
  # Skip some traces if the root span tag values matches some regexp patterns
  # skipTagsPatterns: {"http.url": ".*/demo/add.*"}
  
# Enable custom tracing (Custom annotations for now)
# enableCustomAnnotationTracingOver: ["io","org","com"]

# Disable some instrumentations
# disabledInstrumentations: ["apache http", "mongo", "jetty", "tomcat", ...]

Instrumented frameworks

When attached to an application the dd-java-agent automatically instruments the following set of frameworks & servers:

Frameworks

FWK Versions Comments
OkHTTP 3.x HTTP client calls with cross-process headers
Apache HTTP Client 4.3 + HTTP client calls with cross-process headers
AWS SDK 1.x Trace all client calls to any AWS service
Web Servlet Filters Depending on server See Servers section

Servers

Server Versions Comments
Jetty 8.x, 9.x Trace all incoming HTTP calls with cross-process capabilities
Tomcat 8.0.x, 8.5.x & 9.x Trace all incoming HTTP calls with cross-process capabilities

Modern web application frameworks such as Dropwizard or Spring Boot are automatically instrumented thanks to these servers instrumentation. (See example projects)

Databases

DB Versions Comments
Spring JDBC 4.x Please check the following JDBC instrumentation section
Hibernate 5.x Please check the following JDBC instrumentation section
MongoDB 3.x Intercepts all the calls from the MongoDB client

JDBC instrumentation

By enabling the JDBC instrumentation you'll intercept all the client calls to the following DBs: MySQL, PostgreSQL, H2, HSQLDB, IBM DB2, SQL Server, Oracle, MariaDB, etc...

But unfortunately this can not be done entirely automatically today. To enable tracing please follow the instructions provided on the java-jdbc opentracing contrib project.

We also provide an [example project with Spring Boot & MySQL](web application frameworks).

Disabling instrumentations

If for some reason you need to disable an instrumentation you should uncomment the disabledInstrumentations: attribute in the configuration and provide a list as illustrated below:

...

# Disable a few instrumentations
disabledInstrumentations: ["apache http", "mongo", "tomcat"]

...

Custom instrumentations

The @trace annotation

By adding the @trace annotation to a method the dd-java-agent automatically measures the execution time.

@Trace
public void myMethod() throws InterruptedException{
		...
}

By default, the operation name attached to the spawn span will be the name of the method and no meta tags will be attached.

You can use the operationName and tagsKV attributes to customize your trace:

@Trace(operationName="Before DB",tagsKV={"mytag","myvalue"})
public void myMethod() throws InterruptedException{
	....
}

Enabling custom tracing

  • Add the annotations jar as a dependency of your project
<dependency>
	<groupId>com.datadoghq</groupId>
	<artifactId>dd-trace-annotations</artifactId>
	<version>{version}</version>
</dependency>
  • Enable custom tracing by adding in the dd-trace.yaml config file the packages you would like to scan as follow enableCustomAnnotationTracingOver: ["io","org","com"].

If you want to see custom tracing in action please run the Dropwizard example.

Other useful resources

Before instrumenting your own project you might want to run the provided examples:

Other links that you might want to read: