Highlight .NET 4.x (经典 ASP.NET) 全栈可观测接入指南：OTLP 上报错误、日志、Traces 与 Metrics

发布时间：2026/9/25 3:26:19来源：尧图网络

可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本文基于 Highlight 仓库中的 .NET 4.x 服务端接入文档12_dotnet-4.md展开完整覆盖通过Highlight.ASP4NuGet 包为经典 ASP.NET 4 应用WebForms/MVC非 .NET Core接入错误监控、日志、分布式追踪与指标上报的全部步骤并结合 sdk/highlight-dotnet4 的 SDK 源码解析其底层实现原理注册即自动装配 OpenTelemetry 管线、会话上下文提取与 W3Ctraceparent跨端传播机制。读完本文你可以将一套运行在 .NET 4.x 的遗留 Web 应用接入 Highlight并理解 SDK 内部如何处理 trace、log 和 session 的关联。适用范围与能力矩阵该接入文档面向经典 .NET 4.xASP.NET 4应用与 .NET Core / .NET 5 的接入方式对应文档 11_dotnet.md相互独立。根据 quickstart 内容定义此方式支持的产品能力为产品支持情况Errors错误监控支持通过 ASP.NET 请求异常记录与 Serilog 日志上报Logs日志支持通过 Serilog OpenTelemetry Logs 导出Traces分布式追踪支持自动插桩 ASP.NET、HttpClient、SqlClient、EF CoreMetrics指标支持通过 MeterProvider OTLP 导出接入的传输协议为OpenTelemetry Protocol (OTLP)从 OpenTelemetry.cs 源码可以确认SDK 固定使用HttpProtobuf协议默认上报端点为public const OtlpProtocol Protocol OtlpProtocol.HttpProtobuf; public const OtlpExportProtocol ExportProtocol OtlpExportProtocol.HttpProtobuf; public class Config { public string ProjectId; public string ServiceName; public string OtlpEndpoint https://otel.highlight.io:4318; }即 traces/logs/metrics 分别以 OTLP HTTP/protobuf 发送到{OtlpEndpoint}/v1/traces、/v1/logs、/v1/metrics。仓库中还提供了一个可运行的 ASP.NET 4 示例项目 e2e/dotnet4可作为参照。第一步安装 Highlight .NET SDK经典 .NET 4 项目没有dotnet add命令需要通过 NuGet Package Manager Console 安装Highlight.ASP4包.NET Core 项目则使用dotnet add Highlight.ASPCore二者由同一工厂函数 downloadSnippet 按 flavor 区分生成nuget install Highlight.ASP4第二步在前端模板中注入 traceparent 元标签这是 .NET 接入区别于通用前端接入指南前端接入文档的关键一步为了让浏览器端的 Highlight 采集能够继承服务端的 trace ID 与会话上下文需要在布局模板中输出traceparentmeta 标签。修改Views/Shared/_Layout.cshtml入口模板using OpenTelemetry.Trace functions { // set the traceparent meta tag to the current active span to propagate context to the client string GetTraceParentContext() { var currentTrace Tracer.CurrentSpan; if (!currentTrace.IsRecording) { return 00-00-00-00; } var traceId currentTrace.Context.TraceId; var spanId currentTrace.Context.SpanId; return $00-{traceId.ToHexString()}-{spanId.ToHexString()}-01; } } !DOCTYPE html html head meta nametraceparent contentGetTraceParentContext() script srchttps://unpkg.com/highlight.run/script script H.init(YOUR_PROJECT_ID, { serviceName: highlight-dot-net-frontend, tracingOrigins: true, networkRecording: { enabled: true, recordHeadersAndBody: true, }, }); /script * your standard head contents here... * /head body * your standard body contents here... * RenderSection(scripts, required: false) /body /html说明GetTraceParentContext()按 W3C Trace Context 格式00-{traceId}-{spanId}-01拼接当前活动 span 的 ID当前 span 未处于记录状态时返回全零占位符00-00-00-00前端H.init中tracingOrigins: true表示启用跨域 trace 传播浏览器端上报的 trace 会携带该 traceparent从而与服务端 trace 合并到同一条调用链上networkRecording开启后浏览器端会记录网络请求的 headers 与 body。第三步在 Global.asax.cs 中初始化 Highlight.NET 4 应用没有Program.cs/Startup.cs入口是Global.asax.cs。SDK 的卖点在于Highlight.OpenTelemetry.Register一次调用即完成 OpenTelemetry 的插桩与导出配置文档原文.NET supports OpenTelemetry instrumentation out of the box. The Highlight.ASP4 NuGet package sets up OpenTelemetry instrumentation and export for highlight。using System; using System.Collections.Generic; using System.Linq; using System.Web; using System.Web.Mvc; using System.Web.Optimization; using System.Web.Routing; public class MvcApplication : System.Web.HttpApplication { protected void Application_Start() { AreaRegistration.RegisterAllAreas(); FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters); RouteConfig.RegisterRoutes(RouteTable.Routes); BundleConfig.RegisterBundles(BundleTable.Bundles); Highlight.OpenTelemetry.Register(options { options.ProjectId YOUR_PROJECT_ID; options.ServiceName example-dotnet-backend; }); var logger new LoggerConfiguration() .Enrich.WithHighlight() .WriteTo.HighlightOpenTelemetry(options { options.ProjectId YOUR_PROJECT_ID; options.ServiceName example-dotnet-backend; }) .CreateLogger(); logger.Information(Hello, World!); } protected void Application_End() { Highlight.OpenTelemetry.Unregister(); } }配置项说明对应 Config 类配置项说明ProjectIdHighlight 项目 ID写入每条遥测数据的highlight.project_id资源属性ServiceName服务名写入service.name资源属性同时作为AddSource采集自建 meter/tracer 的源名OtlpEndpointOTLP 上报地址默认https://otel.highlight.io:4318可覆盖在Application_End中调用Unregister()释放TracerProvider与MeterProviderUnregister 实现避免进程退出时资源泄漏。第四步配置 Serilog 日志导出上面Application_Start中同时展示了 Serilog 的接法这是该 SDK 提供日志能力的核心路径——两个 Serilog 扩展方法定义在 OpenTelemetry.csWriteTo.HighlightOpenTelemetry(configure)内部包装Serilog.Sinks.OpenTelemetry的OpenTelemetry()sink固定 OTLP 协议为HttpProtobuf端点为{OtlpEndpoint}/v1/logs并自动附加 Highlight 资源属性Enrich.WithHighlight()挂载LogEnricher将GetHighlightContext()返回的highlight.project_id、service.name、highlight.session_id等上下文属性注入每一条LogEvent。var logger new LoggerConfiguration() .Enrich.WithHighlight() .WriteTo.HighlightOpenTelemetry(options { options.ProjectId YOUR_PROJECT_ID; options.ServiceName example-dotnet-backend; }) .CreateLogger(); logger.Information(Hello, World!);SDK 的 READMEsdk/highlight-dotnet4/README.md中还展示了更完整的异步写法.WriteTo.Async(async async.HighlightOpenTelemetry(...))适合高吞吐场景避免日志 IO 阻塞。源码解析Register 内部装配了什么Register 方法一次性构建了 Trace 与 Metric 两条管线值得逐项了解TracerProvider 构建链_tracerProvider Sdk.CreateTracerProviderBuilder() .SetSampler(new AlwaysOnSampler()) .SetResourceBuilder(ResourceBuilder.CreateDefault().AddAttributes(GetResourceAttributes())) .AddHttpClientInstrumentation() .AddSqlClientInstrumentation(option { option.SetDbStatementForText true; }) .AddEntityFrameworkCoreInstrumentation() .AddAspNetInstrumentation(options { options.RecordException true; options.EnrichWithHttpRequest EnrichWithHttpRequest; options.EnrichWithHttpResponse EnrichWithHttpResponse; }) .AddSource(Cfg.ServiceName) .AddProcessor(new TraceProcessor()) .AddOtlpExporter(exporterOptions { exporterOptions.Endpoint new Uri(Cfg.OtlpEndpoint /v1/traces); exporterOptions.Protocol ExportProtocol; exporterOptions.BatchExportProcessorOptions.MaxExportBatchSize 10000; exporterOptions.BatchExportProcessorOptions.MaxQueueSize 10000; exporterOptions.BatchExportProcessorOptions.ScheduledDelayMilliseconds 1000; }) .Build();自动插桩AddAspNetInstrumentationRecordException true即 HTTP 5xx/未处理异常自动生成错误 span——这就是 Errors 能力的来源、AddHttpClientInstrumentation出站 HTTP 调用、AddSqlClientInstrumentationSQL 查询SetDbStatementForText true保留 SQL 语句文本、AddEntityFrameworkCoreInstrumentationEF Core 数据访问批量导出参数MaxExportBatchSize 10000、MaxQueueSize 10000、ScheduledDelayMilliseconds 1000日志导出器InstrumentLogging使用相同参数说明 SDK 针对写入密集型遥测调大了队列与批量上限防重复注册Register开头有_registered幂等保护重复调用直接返回。会话上下文提取Trace ↔ Session 关联EnrichWithHttpRequest 在 ASP.NET 请求 span 上记录http.client_ip、http.method、http.route、http.request.header.*等标签并调用 ExtractContext 提取会话 ID优先读取请求头x-highlight-requestsessionId/requestId格式该头由前端 SDK 发送若无该头则回退到 ASP.NET 的sessionIDCookie并自动回写sessionID与sessionData_{sessionId}两个 Cookie15 分钟过期sessionData中携带sessionSecureID、projectID、sessionStartTime等信息提取结果写入 span 标签highlight.session_id并放入Baggagex-highlight-request键。后续TraceProcessor/LogProcessor在 span 与 log 启动时从Baggage读取上下文并合并进每条数据——这样同一请求链上的 span 与日志自动共享 session 与 project 属性。源码中多处注释表明trace 的跨端关联刻意依赖 W3Ctraceparent传播而非自有的highlight.trace_id属性见 GetHighlightContext这正是第二步中布局模板必须输出traceparentmeta 标签的底层原因浏览器端读取该 meta 后客户端 trace 与服务端 trace 合并为同一 trace。此外 GetResourceAttributes 会附加telemetry.distro.name Highlight.ASP4与版本号Highlight 后端可据此识别遥测来源为 .NET 4 包。验证接入结果接入完成后按 quickstart 的最后三步逐一验证错误触发一段会报错的代码路径AddAspNetInstrumentation配置了RecordException true未处理异常会被记录到 Highlight errors portal 确认后端错误已被记录日志确认上一步logger.Information(Hello, World!)之类的后端日志出现在 Highlight logs portalTraces到 Highlight traces portal 确认后端 trace 数据流入并验证带traceparentmeta 的页面请求中前后端 trace 合并为一条完整调用链。小结与相关文件索引内容仓库路径本文档源文件.NET 4.x quickstartdocs-content/getting-started/4_server/12_dotnet-4.mdquickstart 内容实际定义安装、前端注入、Global.asax 引导、验证步骤highlight.io/components/QuickstartContent/server/dotnet/dot-net-4.tsx安装命令与前端 snippet 工厂highlight.io/components/QuickstartContent/server/dotnet/shared-snippets-tracing.tsxSDK 核心实现Register/Unregister/上下文提取sdk/highlight-dotnet4/OpenTelemetry.csSDK 使用说明sdk/highlight-dotnet4/README.mdASP.NET 4 示例应用e2e/dotnet4需要注意的前提与限制该接入方式仅适用于经典 ASP.NET 4.NET Framework 4.x应用.NET Core/5 项目应改用 11_dotnet.md 对应的Highlight.ASPCore包上报协议固定为 OTLP HTTP/protobuf端点默认指向https://otel.highlight.io:4318自托管部署时可通过OtlpEndpoint指向自己的 OTLP 接收器。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐Highlight .NET 接入指南用 OTLP 协议为 .NET 6/8 应用接入 Traces、Errors、Logs 与 MetricsHighlight .NET 接入指南用 OTLP 协议为 .NET 6/8 应用接入 Traces、Errors、Logs 与 Metrics 本篇基于 H可观测性后端PinchTab 多实例Multi-Instance运维完全指南隔离浏览器、持久化 Profile 与实例生命周期管理PinchTab 多实例Multi Instance运维完全指南隔离浏览器、持久化 Profile 与实例生命周期管理 PinchTab 是一个高性能浏览Apache Airflow 日志与监控完全指南从任务日志、Metrics、Traces 到健康检查与错误追踪Apache Airflow 日志与监控完全指南从任务日志、Metrics、Traces 到健康检查与错误追踪数据管道通常在没有人工值守的情况下长时间运行后端任务调度工作流自动化数据编排批处理数据工程流程编排上一篇LMMS音频处理插件全攻略5大核心工具实现专业降噪、均衡与限制下一篇AltairAPI使用可视化请求量与错误率监控创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

网站建设高端定制企业官网