skills.rest
DataDog
DataDogOFFICIAL
Explore all skills by this author →
Website𝕏@datadoghqGitHub

apm-integrations

Writes new library instrumentations end-to-end for the dd-trace-java APM agent.

735|355|Updated Apr 24, 2017
Search Tags:#tracing#instrumentation#gradle#datadog#apm#JAVA#bytebuddy
One-click install
npx skills add https://github.com/DataDog/dd-trace-java --skill apm-integrations
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: apm-integrations
Source: https://github.com/DataDog/dd-trace-java/tree/main/.agents/skills/apm-integrations
Command: npx skills add https://github.com/DataDog/dd-trace-java --skill apm-integrations

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Adding a new library instrumentation to Datadog's dd-trace-java agent involves many project-specific conventions — module layout, muzzle directives, decorator patterns, advice rules, config registration, and CI checks — that are easy to get wrong without deep familiarity with the codebase.

Core Features & Use Cases

  • End-to-end instrumentation authoring: Guides creation of the InstrumenterModule, Decorator, Advice classes, context-propagation adapters, and tests following dd-trace-java conventions.
  • Reference-driven rules: Bundled references cover advice-class pitfalls, context-tracking vs span-creating instrumentations, muzzle directive patterns, naming conventions, supported-configurations registration, and test requirements.
  • Verification workflow: Prescribes the exact Gradle commands (muzzle, test, latestDepTest, config checks, spotlessApply) plus a completion checklist and a retrospective step that improves the skill itself.
  • Use Case: Ask to add tracing for a new HTTP client library; the skill locates a similar existing integration, scaffolds the module, writes advice and tests, registers config keys, and runs the full verification suite.

Quick Start

Ask the agent to add a new APM instrumentation for a specific Java library, providing the framework name, minimum supported version, and target classes or methods to instrument.

Frequently Asked Questions about apm-integrations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new library instrumentation to dd-trace-java?▼

Create a module under dd-java-agent/instrumentation/$framework/$framework-$minVersion with an InstrumenterModule, Decorator, and Advice classes, register it in settings.gradle.kts and supported-configurations.json, then add muzzle directives and tests. The skill walks through each step and runs the required Gradle verification tasks.

What is the difference between span-creating and context-tracking instrumentation?▼

Span-creating instrumentation extends InstrumenterModule.Tracing and creates spans around I/O operations like HTTP or database calls. Context-tracking instrumentation extends InstrumenterModule.ContextTracking and only bridges trace context across async boundaries such as reactive libraries or executors, creating no spans itself.

Why does muzzle fail on a new instrumentation module?▼

The most common cause is missing helper class names in helperClassNames(), including inner, anonymous, or enum synthetic classes. Other causes are a version range that does not cover tested versions or an instrumented class that does not exist in the declared compileOnly version.

Should instrumentation tests be written in Groovy or Java?▼

Match the sibling module's test DSL: Groovy/Spock in src/test/groovy is the default, and you must not introduce a Java/JUnit suite into a Groovy family. New .groovy files trigger the Enforce Groovy Migration CI check, which is bypassed with the 'tag: override groovy enforcement' label.

When should I not write a context-tracking instrumentation?▼

If the library performs actual I/O such as HTTP requests, database queries, or messaging, write a span-creating instrumentation instead. Context-tracking is only for libraries that coordinate work across threads or async boundaries without performing I/O themselves.

Related Skills

Explore More Software Engineering Skills→
wesleyegbertowesleyegberto
3

java-jackknife

Inspect JAR contents and decompile classes to diagnose Java dependency issues.

Community
Advanced
tktaftktaf

pr

Automate GitHub Pull Request review and remediation until merged.

Community
Advanced
jamesogunsanjamesogunsan

distributed-tracing

Design OpenTelemetry-first distributed tracing with span naming, propagation, and sampling policies.

Community
Advanced
cedriczielcedricziel

opentelemetry-java

Instrument Java applications with OpenTelemetry for traces, metrics, and context propagation.

Community
Advanced