如何从Azure Function App向App Insights插入自定义日志？

前置准备 #

• 先确认Function App配置中已存在APPLICATIONINSIGHTS_CONNECTION_STRING项，值为目标App Insights实例的连接串。如果创建Function时勾选了关联App Insights，这个配置会自动注入，不需要手动硬编码。
• 根据你用的开发栈安装对应依赖：
  • .NET隔离工作进程模型：安装Microsoft.Azure.Functions.Worker.ApplicationInsights包
  • .NET进程内模型：安装Microsoft.Azure.WebJobs.Logging.ApplicationInsights包
  • Node.js/Python/Java栈：直接使用对应语言的官方Application Insights SDK即可，不需要额外引入冗余依赖

不要自己手写HTTP请求直接打App Insights的接收接口，用SDK自带的客户端会自动带上Function调用ID、实例ID、全链路TraceID等上下文，排查问题的时候能直接串起整条调用链路，省很多事。

核心实现逻辑 #

核心思路是用SDK注入的遥测客户端上报数据，把错误码、错误信息、业务载荷作为自定义维度附在遥测数据上，不要自己封装日志发送逻辑。

.NET 示例代码 #

直接通过构造函数注入单例TelemetryClient，不要手动new客户端：

public class BusinessFunction
{
    private readonly TelemetryClient _telemetryClient;

    // 框架自动注入TelemetryClient，不需要手动初始化
    public BusinessFunction(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }

    [Function("ProcessOrder")]
    public async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
    {
        OrderPayload? orderPayload = null;
        try
        {
            orderPayload = await req.ReadFromJsonAsync<OrderPayload>();
            // 这里写你的业务处理逻辑
            return req.CreateResponse(System.Net.HttpStatusCode.OK);
        }
        catch (Exception ex)
        {
            // 组装自定义上报字段
            var customProps = new Dictionary<string, string>
            {
                ["ErrorCode"] = "ORDER_PROCESS_003", // 自定义业务错误码
                ["ErrorMessage"] = ex.Message, // 错误描述
                ["RequestPayload"] = JsonSerializer.Serialize(orderPayload) // 业务请求载荷
            };

            // 上报异常数据，SDK会自动附带上异常堆栈、调用链路信息
            _telemetryClient.TrackException(ex, customProps);
            
            // 如果需要单独统计业务事件，也可以用TrackEvent上报
            // _telemetryClient.TrackEvent("OrderProcessFailed", customProps);

            // 重点：Function执行结束前必须调用Flush，强制把缓冲区里的日志发出去，不然消费计划下进程被回收会丢日志
            _telemetryClient.Flush();

            return req.CreateResponse(System.Net.HttpStatusCode.InternalServerError);
        }
    }
}

public class OrderPayload
{
    public string OrderId { get; set; }
    public decimal Amount { get; set; }
}

其他语言栈说明 #

• Node.js：引入applicationinsights包后取默认客户端，调用trackException/trackEvent方法时把自定义字段放在properties参数里即可，执行结束前记得调用flush()。
• Python：通过opencensus.ext.azure.log_exporter配置日志导出器，打日志时把错误码、业务载荷放在extra参数里，这些字段会自动同步到App Insights的自定义维度中。
• Java：通过@Inject注入TelemetryClient实例，和.NET用法一致，调用对应track方法传入自定义属性即可。

日志查询验证 #

上报完成后，进入App Insights的日志查询界面，自定义字段会存在遥测数据的customDimensions下，可以直接写KQL查询过滤：

// 查询最近2小时的业务处理错误
exceptions
| where timestamp > ago(2h)
| where customDimensions.ErrorCode == "ORDER_PROCESS_003"
| project 
    timestamp, 
    ErrorCode = customDimensions.ErrorCode, 
    ErrorMsg = customDimensions.ErrorMessage, 
    Payload = customDimensions.RequestPayload, 
    StackTrace = details

避坑提示 #

• 绝对不要每次上报日志都新建一个TelemetryClient实例，一定要用框架注入的单例，不然会丢失链路上下文，还会造成内存泄漏。
• 上报的业务载荷如果包含手机号、身份证号等敏感信息，必须先做脱敏处理，避免合规风险。
• 单条自定义字段的长度不要超过8KB，超过后App Insights会自动截断，大体积内容建议存到Blob存储，日志里只存对应资源地址。
• 如果是本地调试，记得在local.settings.json里也配上APPLICATIONINSIGHTS_CONNECTION_STRING，不然本地运行不会上报日志。

内容的提问来源于stack exchange，提问作者Azure Developer