ApplicationInsights-dotnet TelemetryClient 完全参考8 种 Track 方法的参数与用法详解【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet 是 Azure Application Insights 的官方 .NET SDK核心类TelemetryClient提供了 8 种 Track 方法用于将事件、日志、指标、异常、依赖调用和请求等遥测数据发送到 Azure Monitor。本参考文档逐一详解每个 Track 方法的参数与用法帮助你快速上手。 什么是 TelemetryClientTelemetryClient是向 Application Insights 发送遥测数据的统一入口。在 3.x 版本中它构建在 OpenTelemetry 之上你仍然调用熟悉的TrackXxx()方法SDK 内部会自动将其转换为 OpenTelemetry 的 Activity、LogRecord 和 Metric 信号再发送到 Azure Monitor。核心源码BASE/src/Microsoft.ApplicationInsights/TelemetryClient.cs概念文档docs/concepts.md使用前只需两步var configuration TelemetryConfiguration.CreateDefault(); configuration.ConnectionString InstrumentationKey...;IngestionEndpoint...; var telemetryClient new TelemetryClient(configuration);8 种 Track 方法速览方法用途内部转换TrackEvent自定义业务事件LogRecord带自定义事件标记TrackTrace诊断日志消息LogRecordTrackMetric数值型指标OpenTelemetry HistogramTrackException异常含堆栈LogRecord带异常TrackDependency出站依赖调用DB、HTTP 等ActivityClient/ProducerTrackRequest入站请求ActivityServer/ConsumerTrackAvailability可用性/拨测LogRecordTrack通用分发按类型路由自动调用上述方法 1. TrackEvent — 记录业务事件用于记录发生了什么如用户登录、订单完成。// 最简用法 telemetryClient.TrackEvent(UserLoggedIn); // 带属性可用于检索和分类 telemetryClient.TrackEvent(OrderProcessed, new Dictionarystring, string { { OrderId, 12345 }, { PaymentMethod, CreditCard } }); // 对象形式可精细控制 var evt new EventTelemetry(OrderProcessed); evt.Properties[OrderValue] 249.99; telemetryClient.TrackEvent(evt);参数说明参数类型说明eventNamestring事件名称为空则不发送propertiesIDictionarystring, string命名字符串属性用于检索分类 数值也可以放进 properties转成字符串例如把OrderValue记为249.99。若数据是纯数值度量建议改用TrackMetric。 2. TrackTrace — 记录诊断日志用于在诊断搜索中查看文本日志支持 5 级严重级别。telemetryClient.TrackTrace(Processing started); // 仅消息 telemetryClient.TrackTrace(Order validation failed, SeverityLevel.Warning); // 带级别 telemetryClient.TrackTrace(Retrying, props); // 带属性 telemetryClient.TrackTrace(Critical path down, SeverityLevel.Critical, props); // 全参数 telemetryClient.TrackTrace(new TraceTelemetry(msg)); // 对象形式参数说明参数类型说明messagestring要显示的消息severityLevelSeverityLevel严重级别可省略默认 InformationpropertiesIDictionarystring, string分类属性可省略SeverityLevel 五级枚举定义于BASE/src/Microsoft.ApplicationInsights/DataContracts/SeverityLevel.cs级别含义Verbose详细诊断信息Information一般信息Warning潜在问题的警告Error错误但应用仍可继续Critical严重故障需立即处理 3. TrackMetric — 上报数值指标telemetryClient.TrackMetric(QueueLength, 42); telemetryClient.TrackMetric(ResponseTime, 123.45, new Dictionarystring, string { { Endpoint, /api/users } });参数说明参数类型说明namestring指标名称valuedouble指标值propertiesIDictionarystring, string分段维度可省略⚠️ 官方建议指标应先做时间维度上的预聚合再上报推荐用GetMetric(metricId)获取Metric对象由 SDK 自动聚合后发送见文末进阶。TrackMetric更适合已有自聚合逻辑的场景如果每次发生都要单独上报一条记录那其实是TrackEvent的用途。 4. TrackException — 记录异常try { ProcessOrder(orderId); } catch (Exception ex) { telemetryClient.TrackException(ex, new Dictionarystring, string { { OrderId, orderId } }); throw; // 继续抛出或自行处理 }参数说明参数类型说明exceptionException要记录的异常null 会转为占位异常propertiesIDictionarystring, string分类属性可省略对象形式TrackException(ExceptionTelemetry)可额外指定SeverityLevel、InnerExceptions和自定义Message。更多写法可参考示例 examples/BasicConsoleApp/ExceptionTelemetryExamples.cs。 5. TrackDependency — 记录外部依赖调用用于手动追踪数据库查询、HTTP 出站调用、消息队列等。var startTime DateTimeOffset.UtcNow; var timer System.Diagnostics.Stopwatch.StartNew(); telemetryClient.TrackDependency( HTTP, // 依赖类型 GET /data, // 命令名 https://api.example.com/data, // 完整数据/URL startTime, // 开始时间 timer.Elapsed, // 耗时 true); // 是否成功参数说明两重载参数说明dependencyTypeName依赖类型如HTTP、SQL、Redis低基数target外部目标如dbserver8 参重载才有dependencyName命令名如存储过程名、URL 路径模板低基数data完整命令如 SQL 语句、含查询参数的完整 URLstartTime调用开始时间duration耗时resultCode结果码如200、08 参重载才有success是否成功 SDK 会根据依赖类型自动映射 OpenTelemetry 的 ActivityKindHTTP/SQL→ Client消息队列Queue Message、Service Bus、Event Hubs→ ProducerInProc→ Internal。 6. TrackRequest — 记录入站请求适合非 Web 应用如队列消费者记录处理了什么请求。var startTime DateTimeOffset.UtcNow; var timer System.Diagnostics.Stopwatch.StartNew(); var result await ProcessMessageAsync(message); telemetryClient.TrackRequest( ProcessMessage, // 请求名 startTime, // 开始时间 timer.Elapsed, // 耗时 200, // 响应码 result.Success); // 是否成功参数说明参数类型说明namestring请求名称startTimeDateTimeOffset请求开始时间durationTimeSpan处理耗时responseCodestring响应状态码successbool是否处理成功对象形式TrackRequest(RequestTelemetry)还可设置Url、Source等字段。SDK 按请求特征映射 ActivityKindHTTP(S) → Server队列/主题消费sb://、amqp:// 等→ Consumer。 7. TrackAvailability — 记录可用性探测用于合成监测拨测场景如定时健康检查。var startTime DateTimeOffset.UtcNow; var timer System.Diagnostics.Stopwatch.StartNew(); bool success false; string message null; try { var response await httpClient.GetAsync(https://myapp.example.com/health); success response.IsSuccessStatusCode; message $Status: {response.StatusCode}; } catch (Exception ex) { message ex.Message; } telemetryClient.TrackAvailability( name: Health Check, timeStamp: startTime, duration: timer.Elapsed, runLocation: Environment.MachineName, success: success, message: message);参数说明参数类型说明namestring可用性测试名称timeStampDateTimeOffset探测发生时间durationTimeSpan探测耗时runLocationstring探测执行位置successbool是否成功messagestring失败信息可省略propertiesIDictionarystring, string分类属性可省略 8. Track(ITelemetry) — 通用分发入口当你拿到一个ITelemetry实例但类型不确定时Track会根据实际类型自动路由RequestTelemetry→TrackRequestDependencyTelemetry→TrackDependencyTraceTelemetry→TrackTraceEventTelemetry→TrackEventExceptionTelemetry→TrackException⚠️ 该方法属于 SDK 内部基础设施文档标注 Do not call日常开发请直接使用对应的TrackXxx方法。 最佳实践清单应用退出前调用Flush()遥测是异步批量发送的控制台/Worker 应用退出前务必telemetryClient.Flush()否则可能丢数据。区分 Event 与 Metric一次性发生、需要逐条查看 →TrackEvent可聚合的数值度量 →GetMetric/TrackMetric。低基数命名dependencyName、事件名等字段会被用作分组维度避免放入高基数值如 GUID、完整 URL 含参数。属性字典要可变TrackEvent(string, ...)等重载会向传入的属性字典中写入内部标记建议每次调用传入新字典。禁用遥测设置configuration.DisableTelemetry true必须在创建第一个TelemetryClient之前。 进阶指标聚合与操作关联指标聚合telemetryClient.GetMetric(ResponseTime, Endpoint)返回Metric对象调用TrackValue(value)即可由 SDK 自动聚合上报支持最多 4 个维度。源码BASE/src/Microsoft.ApplicationInsights/Metric.cs操作生命周期扩展方法StartOperationT()/StopOperation()源码BASE/src/Microsoft.ApplicationInsights/TelemetryClientExtensions.cs可自动管理 Activity 并关联操作 IDusing结束即自动发送。完整可运行示例examples/ConsoleApp/Program.cs 演示了全部 8 种 Track 方法 Flush()的组合用法examples/BasicConsoleApp/ 提供异常、指标等更多场景。版本差异2.x → 3.x 的变更见 BreakingChanges.md 与 MigrationGuidance.md。掌握这 8 个 Track 方法你就能覆盖绝大多数手动埋点场景。配合自动采集 SDKNETCORE/Readme.md、WEB/Readme.md使用即可构建完整的 .NET 应用可观测性方案。【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考