---
name: Debug Runtime Integration
slug: debug-runtime-integration
category: Quality
description: Debug Runtime Integration helps identify why NeMo Relay loads but runtime behavior is missing or incorrect, including scope, event, plugin, and export wiring issues. Use it when integration works partially but the expected callbacks or telemetry do not appear.
github: "https://github.com/NVIDIA/NeMo-Relay/tree/main/skills/nemo-relay-debug-runtime-integration"
language: Rust
stars: 165
forks: 67
install: "npx degit https://github.com/NVIDIA/NeMo-Relay/tree/main/skills/nemo-relay-debug-runtime-integration ~/.claude/skills/nemo-relay-debug-runtime-integration"
installs_to: ~/.claude/skills/nemo-relay-debug-runtime-integration
source_path: skills/nemo-relay-debug-runtime-integration/SKILL.md
collection_size: 25
category_size: 1897
collection_url: "https://dirskills.com/collections/NVIDIA/NeMo-Relay"
added: 2026-09-08T05:35:10.207Z
last_synced: 2026-09-08T05:35:10.207Z
canonical_url: "https://dirskills.com/skills/debug-runtime-integration"
---

# Debug Runtime Integration

Debug Runtime Integration helps identify why NeMo Relay loads but runtime behavior is missing or incorrect, including scope, event, plugin, and export wiring issues. Use it when integration works partially but the expected callbacks or telemetry do not appear.

**Install:**

```bash
npx degit https://github.com/NVIDIA/NeMo-Relay/tree/main/skills/nemo-relay-debug-runtime-integration ~/.claude/skills/nemo-relay-debug-runtime-integration
```

## README

# Debug Runtime Integration

Use this skill when NeMo Relay is present in the application but something is not
working.
Start by proving which runtime layer is failing before changing configuration.

## First Checks

- Can the binding or native artifact load?
- Is there an active scope when the failing call runs?
- Is the work happening on the expected scope stack?
- Is the subscriber/exporter/plugin configuration actually active?
- Did the app choose the right public API layer: managed execute vs manual
  lifecycle vs typed wrappers vs adaptive/plugins?

## Common Failure Classes

- Python native extension missing
- Go dynamic library not on the loader path
- Node native addon not built or not loading
- Execute call outside a scope
- Missing events because registration never happened
- Concurrency causing the wrong scope stack to be active
- Adaptive component never initialized or config validation ignored

## Embedded Troubleshooting Matrix

- **Rust build failure**: run the narrowest core build first, then expand to the
  affected binding or workspace command.
- **Python import failure**: rebuild the virtual environment and native
  extension with `uv sync`, then run a small Python test or import check from
  the same environment as the application.
- **Node.js addon failure**: reinstall and rebuild the native addon from the
  Node binding package before debugging application code.
- **Go loader failure**: build the release FFI shared library and point both the
  linker and runtime loader at the release output directory; use the macOS
  dynamic-library path variable (`DYLD_LIBRARY_PATH`) on macOS.
- **Scope stack empty**: the work is outside an active scope or crossed a thread,
  task, goroutine, or worker boundary without the intended stack.
- **Work leaks across requests**: separate requests are sharing one scope stack;
  create a fresh stack per independent request or agent.
- **Middleware missing or ordered incorrectly**: check global vs scope-local
  registration, active scope ancestry, names, and priority values.
- **Subscriber missing events**: register before the events are emitted; for
  scope-local subscribers, ensure the current scope is the owner or descendant.
- **Event fields missing**: managed helpers populate semantic fields; manual
  lifecycle calls require explicit params for input, output, model names, and
  tool call IDs.
- **ATIF empty or mixed**: register before work starts, use one exporter per run
  or clear between runs, and separate concurrent agents by root scope.
- **Provider payload conversion failure**: convert non-JSON provider objects,
  SDK handles, callbacks, streams, or class instances with explicit codecs.
- **Plugin validation failure**: validate config independently from runtime
  registration and check required fields, value types, defaults, and config
  source.
- **Adaptive behavior unchanged**: confirm instrumentation emits events, the
  adaptive component is enabled, policy allows the behavior, and the call path
  reaches the configured component.
- **OpenTelemetry or OpenInference export failure**: first identify the Relay
  version. For 0.6, check the separate exporter, `http_binary` versus `grpc`,
  endpoint, headers, target support, and an active Tokio runtime for native
  gRPC. For 0.7, check the typed projection, endpoint, headers, TLS, and target
  support; the subscriber owns the native gRPC runtime.
- **Callback succeeded but no lifecycle events appear**: confirm the integration
  uses managed execute helpers or balanced manual start/end APIs, not only the
  underlying business callback.

## Related Skills

- `nemo-relay-get-started`
- `nemo-relay-instrument-context-isolation`
- `nemo-relay-plugin-adaptive-tuning`
- `nemo-relay-plugin-build`