Skip to content

feat(skills): add integration-internals and datadog-semantics agent skills#7754

Draft
crysmags wants to merge 1 commit intomasterfrom
crysmags/apm-skills
Draft

feat(skills): add integration-internals and datadog-semantics agent skills#7754
crysmags wants to merge 1 commit intomasterfrom
crysmags/apm-skills

Conversation

@crysmags
Copy link
Collaborator

@crysmags crysmags commented Mar 11, 2026

What does this PR do?

Adds two agent skill files under .agents/skills/ and a targeted fix to the existing orchestrion reference:

New Skills

integration-internals — supplementary deep-dive for integration work alongside apm-integrations:

  • Diagnostic channels internals (runStores vs publish, three channel types, callback wrapping)
  • Shimmer function-type patterns (sync/async/callback/factory, addHook API, double-patching prevention)
  • ESM detection and dual-package handling, esmFirst flag
  • ESM integration testing (subprocess test structure, server.mjs + client.spec.js templates)
  • Debugging with dd-debug (superior to DD_TRACE_DEBUG for channel/span diagnosis)
  • Test environment helpers (createIntegrationTestSuite, Docker services table, externals.json)
  • Performance and hot-path rules

datadog-semantics — APM span naming and tagging conventions:

  • Required and recommended tags per category (database, cache, HTTP client/server, messaging, gRPC, GraphQL)
  • Resource and service naming patterns
  • Span kind selection, error tags, peer service tags
  • get_semantics.py script to query conventions programmatically

Orchestrion fix

Adds a Channel Name Mismatch warning to apm-integrations/references/orchestrion.md: using full apm: channel names in channelName causes double-prefixing at runtime (tracing:orchestrion:{module}:apm:...) which no plugin subscribes to. Short names only (query:start, not apm:mylib:query:start).

Why separate skills?

apm-integrations covers greenfield integration creation. integration-internals and datadog-semantics cover different use cases (debugging regressions, migration from shimmer, span tagging decisions) and are loaded selectively by workflows that need them.

🤖 Generated with APM Instrumentation Toolkit

@crysmags crysmags added the ai-generated PR created with AI assistance label Mar 11, 2026
@github-actions
Copy link
Contributor

github-actions bot commented Mar 11, 2026

Overall package size

Self size: 5.02 MB
Deduped: 5.86 MB
No deduping: 5.86 MB

Dependency sizes | name | version | self size | total size | |------|---------|-----------|------------| | import-in-the-middle | 3.0.0 | 81.15 kB | 815.98 kB | | dc-polyfill | 0.1.10 | 26.73 kB | 26.73 kB |

🤖 This report was automatically generated by heaviest-objects-in-the-universe

@codecov
Copy link

codecov bot commented Mar 11, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.42%. Comparing base (f31802d) to head (e8bf2b3).

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #7754   +/-   ##
=======================================
  Coverage   80.42%   80.42%           
=======================================
  Files         741      741           
  Lines       32168    32168           
=======================================
  Hits        25872    25872           
  Misses       6296     6296           
Flag Coverage Δ
aiguard-macos ?
aiguard-ubuntu 38.95% <ø> (-0.10%) ⬇️
aiguard-windows 38.68% <ø> (-0.10%) ⬇️
apm-capabilities-tracing-macos 48.89% <ø> (ø)
apm-capabilities-tracing-ubuntu 48.93% <ø> (ø)
apm-capabilities-tracing-windows 48.66% <ø> (+<0.01%) ⬆️
apm-integrations-child-process 38.39% <ø> (-0.10%) ⬇️
apm-integrations-couchbase-18 37.31% <ø> (-0.10%) ⬇️
apm-integrations-couchbase-eol 37.78% <ø> (-0.13%) ⬇️
apm-integrations-oracledb 37.62% <ø> (-0.10%) ⬇️
appsec-express 55.20% <ø> (-0.07%) ⬇️
appsec-fastify 51.54% <ø> (-0.07%) ⬇️
appsec-graphql 51.74% <ø> (-0.07%) ⬇️
appsec-kafka 44.27% <ø> (-0.08%) ⬇️
appsec-ldapjs 43.93% <ø> (-0.08%) ⬇️
appsec-lodash 43.59% <ø> (-0.08%) ⬇️
appsec-macos 58.21% <ø> (-0.07%) ⬇️
appsec-mongodb-core 48.70% <ø> (-0.09%) ⬇️
appsec-mongoose 49.37% <ø> (-0.08%) ⬇️
appsec-mysql 50.80% <ø> (-0.17%) ⬇️
appsec-node-serialize 43.11% <ø> (-0.08%) ⬇️
appsec-passport 47.55% <ø> (-0.09%) ⬇️
appsec-postgres 50.52% <ø> (-0.09%) ⬇️
appsec-sourcing 42.51% <ø> (-0.08%) ⬇️
appsec-template 43.27% <ø> (-0.08%) ⬇️
appsec-ubuntu 58.29% <ø> (-0.07%) ⬇️
appsec-windows 58.07% <ø> (-0.07%) ⬇️
instrumentations-instrumentation-bluebird 32.26% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-body-parser 40.41% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-child_process 37.71% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-cookie-parser 34.24% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-express 34.56% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-express-mongo-sanitize 34.37% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-express-session 40.05% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-fs 31.88% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-generic-pool 29.69% <ø> (ø)
instrumentations-instrumentation-http 39.69% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-knex 32.27% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-mongoose 33.39% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-multer 40.16% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-mysql2 38.17% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-passport 43.97% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-passport-http 43.64% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-passport-local 44.17% <ø> (-0.09%) ⬇️
instrumentations-instrumentation-pg 37.60% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-promise 32.19% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-promise-js 32.20% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-q 32.24% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-url 32.17% <ø> (-0.10%) ⬇️
instrumentations-instrumentation-when 32.21% <ø> (-0.10%) ⬇️
llmobs-ai 42.15% <ø> (-0.09%) ⬇️
llmobs-anthropic 40.14% <ø> (-0.09%) ⬇️
llmobs-bedrock 39.13% <ø> (-0.08%) ⬇️
llmobs-google-genai 39.81% <ø> (+0.04%) ⬆️
llmobs-langchain 39.93% <ø> (-0.19%) ⬇️
llmobs-openai 43.87% <ø> (-0.09%) ⬇️
llmobs-vertex-ai 39.94% <ø> (-0.09%) ⬇️
platform-core 31.53% <ø> (ø)
platform-esbuild 34.48% <ø> (ø)
platform-instrumentations-misc 48.40% <ø> (ø)
platform-shimmer 37.63% <ø> (ø)
platform-unit-guardrails 32.95% <ø> (ø)
plugins-azure-event-hubs 25.83% <ø> (ø)
plugins-azure-service-bus 25.19% <ø> (ø)
plugins-bullmq 44.16% <ø> (+<0.01%) ⬆️
plugins-cassandra 37.66% <ø> (-0.10%) ⬇️
plugins-cookie 26.89% <ø> (ø)
plugins-cookie-parser 26.67% <ø> (ø)
plugins-crypto 26.79% <ø> (ø)
plugins-dd-trace-api 38.22% <ø> (-0.10%) ⬇️
plugins-express-mongo-sanitize 26.82% <ø> (ø)
plugins-express-session 26.63% <ø> (ø)
plugins-fastify 42.13% <ø> (-0.09%) ⬇️
plugins-fetch 38.22% <ø> (-0.09%) ⬇️
plugins-fs 38.49% <ø> (-0.10%) ⬇️
plugins-generic-pool 25.87% <ø> (ø)
plugins-google-cloud-pubsub 45.32% <ø> (-0.09%) ⬇️
plugins-grpc 40.81% <ø> (-0.09%) ⬇️
plugins-handlebars 26.86% <ø> (ø)
plugins-hapi 40.04% <ø> (-0.10%) ⬇️
plugins-hono 40.30% <ø> (-0.10%) ⬇️
plugins-ioredis 38.30% <ø> (-0.10%) ⬇️
plugins-knex 26.50% <ø> (ø)
plugins-ldapjs 24.36% <ø> (ø)
plugins-light-my-request 26.23% <ø> (ø)
plugins-limitd-client 32.54% <ø> (-0.10%) ⬇️
plugins-lodash 25.96% <ø> (ø)
plugins-mariadb 39.35% <ø> (-0.15%) ⬇️
plugins-memcached 38.03% <ø> (-0.10%) ⬇️
plugins-microgateway-core 39.18% <ø> (-0.02%) ⬇️
plugins-moleculer 40.40% <ø> (-0.09%) ⬇️
plugins-mongodb 39.05% <ø> (-0.10%) ⬇️
plugins-mongodb-core 38.88% <ø> (-0.10%) ⬇️
plugins-mongoose 38.74% <ø> (-0.10%) ⬇️
plugins-multer 26.63% <ø> (ø)
plugins-mysql 39.18% <ø> (+0.04%) ⬆️
plugins-mysql2 39.14% <ø> (-0.10%) ⬇️
plugins-node-serialize 26.93% <ø> (ø)
plugins-opensearch 37.49% <ø> (-0.10%) ⬇️
plugins-passport-http 26.68% <ø> (ø)
plugins-postgres 35.53% <ø> (-0.09%) ⬇️
plugins-process 26.79% <ø> (ø)
plugins-pug 26.89% <ø> (ø)
plugins-redis 38.77% <ø> (-0.10%) ⬇️
plugins-router 42.99% <ø> (+0.04%) ⬆️
plugins-sequelize 25.47% <ø> (ø)
plugins-test-and-upstream-amqp10 38.38% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-amqplib 43.75% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-apollo 39.01% <ø> (-0.09%) ⬇️
plugins-test-and-upstream-avsc 38.55% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-bunyan 33.80% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-connect 40.70% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-graphql 40.00% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-koa 40.43% <ø> (+0.04%) ⬆️
plugins-test-and-upstream-protobufjs 38.78% <ø> (-0.10%) ⬇️
plugins-test-and-upstream-rhea 43.91% <ø> (-0.10%) ⬇️
plugins-undici 38.99% <ø> (-0.09%) ⬇️
plugins-url 26.79% <ø> (ø)
plugins-valkey 37.97% <ø> (-0.10%) ⬇️
plugins-vm 26.79% <ø> (ø)
plugins-winston 33.99% <ø> (-0.10%) ⬇️
plugins-ws 41.76% <ø> (-0.10%) ⬇️
profiling-macos 39.80% <ø> (-0.10%) ⬇️
profiling-ubuntu 39.92% <ø> (-0.10%) ⬇️
profiling-windows 41.51% <ø> (+0.30%) ⬆️
serverless-azure-functions-client 25.54% <ø> (ø)
serverless-azure-functions-eventhubs 25.54% <ø> (ø)
serverless-azure-functions-servicebus 25.54% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@datadog-prod-us1-5
Copy link

datadog-prod-us1-5 bot commented Mar 11, 2026

⚠️ Tests

Fix all issues with BitsAI or with Cursor

⚠️ Warnings

🧪 1 Test failed

AIGuard SDK "before each" hook for "test evaluate 'tool call' with ALLOW action (blocking: true)" from AIGuard SDK (Datadog) (Fix with Cursor)
Timeout of 5000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves. (/Users/runner/work/dd-trace-js/dd-trace-js/packages/dd-trace/test/aiguard/index.spec.js)

Error: Timeout of 5000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves. (/Users/runner/work/dd-trace-js/dd-trace-js/packages/dd-trace/test/aiguard/index.spec.js)
    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)

ℹ️ Info

No other issues found (see more)

❄️ No new flaky tests detected

This comment will be updated automatically if new data arrives.
🔗 Commit SHA: e8bf2b3 | Docs | Datadog PR Page | Was this helpful? React with 👍/👎 or give us feedback!

@pr-commenter
Copy link

pr-commenter bot commented Mar 11, 2026

Benchmarks

Benchmark execution time: 2026-03-12 21:10:07

Comparing candidate commit e8bf2b3 in PR branch crysmags/apm-skills with baseline commit f31802d in branch master.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 230 metrics, 30 unstable metrics.

@wconti27
Copy link
Contributor

IMO we should close this, and bolster the already existing apm-integrations skill if any of this context is 100% needed

…kills

- integration-internals: deep-dive on diagnostic channels, shimmer patterns,
  ESM support, test environment, debugging (dd-debug), and performance rules
- datadog-semantics: span naming conventions, required/recommended tags per
  category (database, cache, HTTP, messaging, gRPC, GraphQL), and get_semantics.py

Also adds channel name mismatch warning to orchestrion.md: using full apm:
channel names in channelName causes double-prefixing at runtime — short names only.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@crysmags crysmags force-pushed the crysmags/apm-skills branch from b93a971 to e8bf2b3 Compare March 12, 2026 20:59
@crysmags crysmags changed the title feat(skills): add integration-internals, datadog-semantics, and observability-patterns agent skills feat(skills): add integration-internals and datadog-semantics agent skills Mar 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-generated PR created with AI assistance

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants