Skip to main content

CodeXray .NET Agent

How you send .NET telemetry to CodeXray depends on your runtime version. Both paths are zero-code, and both produce the same traces, metrics, and logs in the CodeXray UI — you just pick the one that matches your .NET version.

Two paths, split by version
  • Legacy — CodeXray .NET Agent. For .NET Framework 4.6.1 and earlier (classic Framework on Windows / IIS). OpenTelemetry's auto-instrumentation doesn't run on these older runtimes, so the CodeXray Agent is how you instrument them.
  • Modern — OpenTelemetry Auto-Instrumentation. For .NET Framework 4.6.2+ and .NET 8+. The standard OpenTelemetry .NET automatic instrumentation, pointed at CodeXray.

Which path should you use?​

Your runtimeUse
.NET Framework 4.5 – 4.6.1CodeXray .NET Agent (Path A, below)
.NET Framework 4.6.2, 4.7, 4.8OpenTelemetry Auto-Instrumentation (Path B, below)
.NET 8 and laterOpenTelemetry Auto-Instrumentation (Path B, below)

Why the split at 4.6.2? That's the oldest runtime the OpenTelemetry .NET auto-instrumentation supports. Anything below it — the .NET Framework 4.6.0 / 4.6.1 and 4.5.x apps still common on Windows and IIS — is covered by the CodeXray .NET Agent instead.

On an older "modern" .NET (Core 3.1, .NET 5 / 6 / 7)?

Those runtimes are out of support upstream and aren't covered by the current OpenTelemetry auto-instrumentation. Upgrade to .NET 8 or later to use Path B.

How the data flows​

Both paths land the same data in the same backend — services, traces, logs, metrics, and the DB Insights tab look identical whichever you use, and you can mix them across services in one project.

Path A — CodeXray .NET Agent (.NET Framework 4.6.1 and earlier)​

The CodeXray .NET Agent instruments legacy .NET Framework applications on Windows with no code changes. It attaches through the CLR profiling API when your process starts and captures traces, metrics, and logs automatically.

Runtime.NET Framework 4.5 – 4.6.1 (Windows)
HostingIIS applications, Windows Services, console / long-running executables
SignalsTraces, metrics, logs

Requirements​

  • Windows Server 2012 R2 or later
  • Administrator privileges — the installer registers a CLR profiler machine-wide
  • IIS for web applications
  • Your CodeXray project API key and collector endpoint (from onboarding)

Install​

  1. Download Codexray_DotNetAgent_x64.msi from your CodeXray releases page.
  2. Install it from an elevated prompt, pointing it at your CodeXray endpoint and key:
msiexec /i Codexray_DotNetAgent_x64.msi /qn `
  SS_LICENSE_HOST=<your-codexray-host> SS_LICENSE_PORT=<port> `
  SS_HTTP_PROTOCOL=https SS_LICENSE_KEY=<your-project-api-key> `
  /l*v install.log
  1. Restart IIS — this step is not optional:
iisreset
Restart IIS after installing

IIS worker processes read their environment once, at startup. Until you run iisreset (or restart the target Windows Service), the process has never seen the profiler settings the installer just applied — so nothing is instrumented and no data appears. This is the most common "the agent isn't working" cause.

Configure — codexray.ini​

The agent's configuration lives at C:\Program Files\Codexray\codexray.ini. A complete example:

<configuration xmlns="urn:Codexray-config" agentEnabled="true">

  <!-- Your CodeXray endpoint and project API key -->
  <backendCollector host="<your-codexray-host>" port="<port>" transportType="http">
    <account name="my-service-name" authlicense="<your-project-api-key>"/>
  </backendCollector>

  <!-- IIS: instrument every application pool -->
  <IIS>
    <defaultBehavior instrument="true"/>
    <applicationPools>
      <!-- Or override per pool:
      <applicationPool name="MyAppPool" instrument="true"/> -->
    </applicationPools>
  </IIS>

  <!-- Windows Services / standalone executables to instrument -->
  <windowsApplications>
    <applications>
      <!-- <application name="MyService.exe"/> -->
    </applications>
  </windowsApplications>

  <!-- Required for LOGS (traces and metrics work without it) -->
  <applicationLogging enabled="true">
    <metrics enabled="true"/>
    <forwarding enabled="true" maxSamplesStored="10000"/>
  </applicationLogging>

  <log level="info"/>
</configuration>
SettingWhat it does
backendCollector host / portYour CodeXray collector endpoint
account nameThe service name shown in the Applications view
account authlicenseYour CodeXray project API key
IIS/defaultBehavior instrumentAuto-instrument all IIS app pools (per-pool overrides available)
windowsApplications/applicationsNon-IIS processes (Windows Services, .exe) to instrument
applicationLoggingEnables log capture — required for logs; traces and metrics don't need it
log leveloff · error · warn · info · debug
IIS vs. standalone apps

IIS applications are covered by <defaultBehavior instrument="true"/> automatically. A Windows Service or console .exe must be named under <windowsApplications> to be instrumented — if a standalone app shows no data, this is almost always why.

Logs need <applicationLogging>

Traces and metrics flow as soon as the profiler attaches. Logs additionally require the <applicationLogging> block above, with a non-zero maxSamplesStored. Log lines are captured from inside a request, so anything logged at startup (outside a request) is not sent.

Verify​

  1. Restart IIS / the service and generate some traffic.
  2. In the CodeXray UI, your service appears in the Applications list within a minute or two — check Overview (RED metrics), Traces, and Logs.
  3. If you need to confirm the agent connected, its logs are under C:\Program Files\Codexray\logs\.

Path B — OpenTelemetry Auto-Instrumentation (.NET Framework 4.6.2+ / .NET 8+)​

For modern runtimes, use the OpenTelemetry .NET Automatic Instrumentation — the standard, open-source, zero-code instrumenter — and point it at CodeXray. No CodeXray-specific package and no code changes; it captures traces, metrics, and logs.

Works with: .NET Framework 4.6.2 and later (4.7, 4.8) and .NET 8 and later, on Windows and Linux.

1. Install the auto-instrumentation​

Windows (PowerShell):

# Download and import the installer module, then install the core files
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing
Import-Module $download_path
Install-OpenTelemetryCore

Linux (bash):

curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O
sh ./otel-dotnet-auto-install.sh

2. Point it at CodeXray​

Set these standard OpenTelemetry environment variables:

OTEL_SERVICE_NAME=my-dotnet-service
OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-codexray-collector>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=<your-project-api-key>
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=1.0.0

3. Run your app under instrumentation​

Windows — a console or service app in the current session:

Register-OpenTelemetryForCurrentSession -OTelServiceName "my-dotnet-service"
# then start your application

Windows — IIS:

Register-OpenTelemetryForIIS
iisreset

Linux:

. $HOME/.otel-dotnet-auto/instrument.sh
OTEL_SERVICE_NAME=my-dotnet-service ./MyApp

That's it — traces, metrics, and logs begin arriving within a minute.

Use the same endpoint everywhere

The OTEL_EXPORTER_OTLP_ENDPOINT and x-api-key header are the same ones every OpenTelemetry SDK uses, so services already emitting OpenTelemetry can point at CodeXray without the auto-instrumenter — see the OpenTelemetry SDK guides for the equivalent setup in other languages.

Verifying it's working​

Regardless of path:

  1. Applications list — the service appears in the CodeXray Applications list within a minute or two of receiving traffic.
  2. Signals — open the service and check Overview (RED metrics), Traces for spans, Logs for log lines, and DB Insights for database calls.
  3. Topology — the service shows up on the service map as soon as outbound calls are captured.
Troubleshooting
  • No data (Path A): confirm you ran iisreset after installing, that the authlicense in codexray.ini is a valid project API key, and that the host can reach your CodeXray endpoint. For a standalone .exe, check it's listed under <windowsApplications>.
  • Traces arrive but logs don't (Path A): add the <applicationLogging> block, and make sure the log calls happen inside a request.
  • No data (Path B): confirm OTEL_EXPORTER_OTLP_ENDPOINT is reachable and the x-api-key header is set. The auto-instrumentation logs failed exports explicitly.

Next Steps​