# dotnetcore-trace-test

**Repository Path**: baihr/dotnetcore-trace-test

## Basic Information

- **Project Name**: dotnetcore-trace-test
- **Description**: dotnetcore-trace-test
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dotnetcore-trace-test

ASP.NET Core 链路追踪测试应用，运行在 `http://0.0.0.0:5088`。

## 功能

- `GET /health`：健康检查。
- `GET /slow`：固定延迟 3 秒的慢接口。
- `GET /oracle/ping`：使用 `Oracle.ManagedDataAccess.Client` 打开 Oracle 连接并执行测试 SQL。
- `FixedIntervalOracleWorker`：后台 while 循环任务，每 `Worker:IntervalSeconds` 秒执行一次 Oracle 探测。

## 环境和依赖

### .NET

- 目标框架：`.NET 8`，项目文件中配置为 `net8.0`。
- 当前服务器验证版本：`.NET SDK 8.0.421`。
- 当前服务器运行时：
  - `Microsoft.NETCore.App 8.0.27`
  - `Microsoft.AspNetCore.App 8.0.27`
- 默认 SDK 路径：`C:\dotnet\dotnet.exe`。

查看本机 .NET 版本：

```powershell
C:\dotnet\dotnet.exe --version
C:\dotnet\dotnet.exe --list-sdks
C:\dotnet\dotnet.exe --list-runtimes
```

### NuGet 依赖

项目依赖定义在 `dotnetcore-trace-test.csproj`：

```xml
<PackageReference Include="Oracle.ManagedDataAccess.Core" Version="23.26.200" />
```

说明：

- `Microsoft.NET.Sdk.Web`：ASP.NET Core Minimal API 应用所需 SDK。
- `Oracle.ManagedDataAccess.Core 23.26.200`：Oracle 官方托管驱动，代码中通过 `Oracle.ManagedDataAccess.Client` 命名空间使用。
- `System.Diagnostics.ActivitySource`：.NET 内置手动埋点 API，不需要额外安装 OpenTelemetry SDK NuGet 包。

### 外部运行依赖

- Oracle 数据库：当前按 Oracle AI Database Free 26ai 准备，服务名示例为 `FREEPDB1.localdomain`。
- Oracle 监听端口：`1521`。
- Datadog Agent：应用默认把 trace 发到 `http://localhost:9529`，可通过 `DD_TRACE_AGENT_URL` 调整。
- Datadog .NET Tracer：需要在服务器安装 Datadog .NET tracer，启动时通过 `CORECLR_ENABLE_PROFILING=1` 启用自动注入。

当前 `start.bat` 中使用的关键 Datadog 环境变量：

```bat
set CORECLR_ENABLE_PROFILING=1
set DD_SERVICE=dotnetcore-trace-test
set DD_ENV=test
set DD_VERSION=1.0.0
set DD_TRACE_AGENT_URL=http://localhost:9529
set DD_TRACE_OTEL_ENABLED=true
```

## 手动埋点说明

HTTP 接口不需要手动埋点，Datadog .NET tracer 会自动采集请求 span 和 Oracle span。

后台 while 任务没有 HTTP 请求作为 trace 根节点，所以代码中只在 `FixedIntervalOracleWorker` 的每一轮循环外层创建一个手动 job span。Oracle 调用仍然交给 Datadog 自动埋点，最终 trace 结构类似：

```text
fixed-interval-oracle-probe
  -> select sys_context('USERENV','CON_NAME') from dual
     -> Oracle driver spans
```

启动时需要设置：

```bat
set DD_TRACE_OTEL_ENABLED=true
```

这样 Datadog tracer 才会把 .NET `System.Diagnostics.ActivitySource` 创建的手动 span 采集进去。

## 构建和运行

以下命令默认项目位于 `C:\dotnetcore-trace-test`，.NET SDK 位于 `C:\dotnet\dotnet.exe`。

### 还原依赖

```powershell
Set-Location C:\dotnetcore-trace-test
C:\dotnet\dotnet.exe restore
```

### 构建

```powershell
Set-Location C:\dotnetcore-trace-test
C:\dotnet\dotnet.exe build -c Release
```

### 直接运行源码

开发或临时验证时可以直接运行项目源码：

```powershell
Set-Location C:\dotnetcore-trace-test
C:\dotnet\dotnet.exe run -c Release
```

如果需要同时验证 Datadog trace 采集，可以先设置 Datadog 环境变量：

```powershell
$env:CORECLR_ENABLE_PROFILING = "1"
$env:DD_SERVICE = "dotnetcore-trace-test"
$env:DD_ENV = "test"
$env:DD_VERSION = "1.0.0"
$env:DD_TRACE_AGENT_URL = "http://localhost:9529"
$env:DD_LOGS_INJECTION = "true"
$env:DD_RUNTIME_METRICS_ENABLED = "true"
$env:DD_TRACE_OTEL_ENABLED = "true"

Set-Location C:\dotnetcore-trace-test
C:\dotnet\dotnet.exe run -c Release
```

### 发布

部署时先发布到 `C:\dotnetcore-trace-test\publish`：

```powershell
Set-Location C:\dotnetcore-trace-test
C:\dotnet\dotnet.exe publish -c Release -o C:\dotnetcore-trace-test\publish
```

如果应用正在运行，发布前先停止，避免发布文件被占用：

```powershell
C:\dotnetcore-trace-test\stop.bat
Set-Location C:\dotnetcore-trace-test
C:\dotnet\dotnet.exe publish -c Release -o C:\dotnetcore-trace-test\publish
```

### 手动启动和停止

当前项目不使用计划任务开机启动。需要测试时手动启动：

```powershell
C:\dotnetcore-trace-test\start.bat
```

停止应用：

```powershell
C:\dotnetcore-trace-test\stop.bat
```

启动后可以用下面的命令验证：

```powershell
Invoke-RestMethod http://127.0.0.1:5088/health
Invoke-RestMethod http://127.0.0.1:5088/oracle/ping
Invoke-RestMethod http://127.0.0.1:5088/slow
```

## Oracle 连接串

推荐通过环境变量覆盖连接串，避免把真实密码提交到仓库：

```powershell
$env:Oracle__ConnectionString = "User Id=TRACE_TEST;Password=<TraceUserPassword>;Data Source=localhost:1521/FREEPDB1.localdomain"
C:\dotnet\dotnet.exe C:\dotnetcore-trace-test\publish\dotnetcore-trace-test.dll
```

## Oracle AI Database Free 26ai 安装初始化

以下命令在 Windows 管理员 PowerShell 中执行。Oracle 官方下载页列出的 Windows 包名是 `oracle-ai-database-free-26ai-23.26.1.windows.x64.zip`，静默安装命令参考 Oracle Windows 安装指南。

### 下载

```powershell
$WorkDir = "C:\oracle-free-install"
$ZipPath = Join-Path $WorkDir "oracle-ai-database-free-26ai-23.26.1.windows.x64.zip"
$DownloadUrl = "https://download.oracle.com/otn-pub/otn_software/db-free/oracle-ai-database-free-26ai-23.26.1.windows.x64.zip"

New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null
Invoke-WebRequest -Uri $DownloadUrl -OutFile $ZipPath

# 可选：校验 SHA256，官方页面当前值为 7c673e5f495c03c9cb7ad09b08886a95597f0db9893d727934e370f73b6aa8d0。
Get-FileHash -Algorithm SHA256 $ZipPath
```

### 解压并修改静默安装响应文件

```powershell
$OracleAdminPassword = "<OracleAdminPassword>"
$InstallDir = "C:\app\Administrator\product\26ai"

Expand-Archive -Path $ZipPath -DestinationPath $WorkDir -Force

$RspPath = Join-Path $WorkDir "response\FREEInstall.rsp"
$Rsp = Get-Content $RspPath
$Rsp = $Rsp -replace "^INSTALLDIR=.*", "INSTALLDIR=$InstallDir"
$Rsp = $Rsp -replace "^PASSWORD=.*", "PASSWORD=$OracleAdminPassword"
$Rsp = $Rsp -replace "^LISTENER_PORT=.*", "LISTENER_PORT=1521"
$Rsp = $Rsp -replace "^CHAR_SET=.*", "CHAR_SET=AL32UTF8"
$Rsp = $Rsp -replace "^DB_DOMAIN=.*", "DB_DOMAIN=localdomain"
$Rsp = $Rsp -replace "^SOFTWARE_ONLY=.*", "SOFTWARE_ONLY=FALSE"
$Rsp = $Rsp -replace "^MODIFY_DIRECTORY_PERMISSIONS=.*", "MODIFY_DIRECTORY_PERMISSIONS=TRUE"
Set-Content -Path $RspPath -Value $Rsp -Encoding ASCII
```

### 静默安装

```powershell
Set-Location $WorkDir
.\setup.exe /s /v"RSP_FILE=$RspPath" /v"/L*v $WorkDir\setup.log" /v"/qn"

# 静默安装是异步执行的，可以通过日志确认完成状态。
Get-Content "$WorkDir\setup.log" -Tail 80
```

安装成功后，常见服务名如下；如果服务名不同，用 `Get-Service Oracle*` 查看实际名称。

```powershell
Get-Service Oracle*
Start-Service OracleServiceFREE
Start-Service OracleOraDB23Home1TNSListener
```

### 初始化测试用户

```powershell
$OracleHome = "C:\app\Administrator\product\26ai\dbhomeFree"
$SqlPlus = Join-Path $OracleHome "bin\sqlplus.exe"
$OracleAdminPassword = "<OracleAdminPassword>"
$TraceUserPassword = "<TraceUserPassword>"

$Sql = @"
whenever sqlerror exit sql.sqlcode
declare
  user_count number;
begin
  select count(*) into user_count from dba_users where username = 'TRACE_TEST';

  if user_count = 0 then
    execute immediate 'create user TRACE_TEST identified by "$TraceUserPassword"';
  else
    execute immediate 'alter user TRACE_TEST identified by "$TraceUserPassword" account unlock';
  end if;
end;
/
grant create session to TRACE_TEST;
exit
"@

$Sql | & $SqlPlus -L "sys/$OracleAdminPassword@localhost:1521/FREEPDB1 as sysdba"
```

### 验证连接并配置应用

```powershell
$TraceUserPassword = "<TraceUserPassword>"
$ConnectionString = "User Id=TRACE_TEST;Password=$TraceUserPassword;Data Source=localhost:1521/FREEPDB1.localdomain"

$env:Oracle__ConnectionString = $ConnectionString
C:\dotnet\dotnet.exe C:\dotnetcore-trace-test\publish\dotnetcore-trace-test.dll
```

应用启动后访问：

```powershell
Invoke-RestMethod http://127.0.0.1:5088/health
Invoke-RestMethod http://127.0.0.1:5088/oracle/ping
Invoke-RestMethod http://127.0.0.1:5088/slow
```

## 参考

- Oracle AI Database Free 26ai 下载页：https://www.oracle.com/database/free/get-started/
- Oracle AI Database Free 26ai Windows 安装指南：https://docs.oracle.com/en/database/oracle/oracle-database/26/xeinw/installing-oracle-database-xe.html