Skip to content

App Insights Logging Guidance

Some guidance for logging to App Insights, in general:

  • Any workflow or background process should log state changes as custom_events.
  • Any numeric value that can be tracked as an average over time should be sent as a custom_metric.
  • Anything that triggers the app to act (mostly HTTP requests) must log a request.
  • (auto-instrumentation handles this for nearly all HTTP server implementations).
  • Any outbound connection to a resource or service should be logged as a dependency.
  • (auto-instrumentation handles this for most HTTP clients, in addition to Azure SDK connections).
  • Errors (unexpected or otherwise) should be logged using the appropriate severity type for the runtime, so that it creates telemetry for an exception in App Insights.
  • (likewise, this is often handled by the App Insights SDK/package, depending on language. Azure's documentation is thorough).
  • Errors should generally be actionable and unexpected. If all functions are simply catching errors, logging them, and then proceeding with the execution, then the mass of exceptions will cause them to lose meaning and their usefulness as a signal. You must be as defensive as possible so that all potential error paths are handled upfront, so they don't need to be logged as errors at all (in which case, logging as basic STDOUT is appropriate, which are sent to App Insights as trace telemetry).
  • NEVER log something such that the telemetry's "Name" or "Operation Name" fields will include an ID, GUID, Date, Collection Item, or other value with high cardinality. That information is included in other properties of the telemetry (usually automatic). Those fields need to be used by App Insights dashboards and other features, in addition to user queries, for grouping and summarizing in order to work properly. If they are titled like GET /api/module/af3d25cc-0586-4437-9774-d991eb5f567d instead of GET /api/modules/[GUID], then angels will weep.
  • All access to Azure services made using the Azure SDK should be made using System-Assigned Managed Identity. As such, no credentials, secrets, or tokens need to be managed by the app.