HowTo: Configure diginsight telemetry to the local text based streams

You can obtain a console log or file log with diginsight by means of the steps shown below.

The code snippets are available as working samples within the telemetry.samples repository.
Article HOWTO - Use Diginsight Samples.md: explores how we can use diginsight samples to test and understand integration of Diginsight telemetry in our own projects.

STEP 01 - Add a package reference to the package Diginsight.Diagnostics or Diginsight.Diagnostics.Log4Net

In the first step you can just add a diginsight reference to your code:
reference to Diginsight.Diagnostics is needed for the Console log and Diginsight.Diagnostics.Log4Net is required to enable Log4Net File log.

STEP 02 - Configure logging within the Startup sequence

In the second step you can configure the startup sequence to enable diginsight log:

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);
    var services = builder.Services;
    var configuration = builder.Configuration;
    var environment = builder.Environment;

    // Add logging providers
    services.AddObservability(configuration, environment);

    services.AddControllers();
    services.AddEndpointsApiExplorer();
    services.AddSwaggerGen();

    // Use diginsight service provider 
    // this enables telemetry initialization at service provider creation
    builder.Host.UseDiginsightServiceProvider(true);
    WebApplication app = builder.Build();

    if (app.Environment.IsDevelopment())
    {
        app.UseSwagger();
        app.UseSwaggerUI();
    }

    app.UseHttpsRedirection();

    app.UseAuthorization();

    app.MapControllers();

    app.Run();
}

in the code above: - AddObservability() is used to add log to the application Console and a log4net file log. - UseDiginsightServiceProvider() is used to activate diginsight during the service provider build() process.

Please note that AddObservability() is implemented as an extension method that calls AddLogging() with: - AddDiginsightConsole(): this methods configures the Console log provider with some formatting options

• AddDiginsightLog4Net(): this methods configures a rolling File log on the user profile folder.

Configuration Structure

The code above loads telemetry based on the Diginsight:Activities configuration section that controls activity sources, logging behavior, and optionally metric recording.

Basic Configuration Example

{
  "Diginsight": {
    "Activities": {
      // Activity source filtering - which sources to listen to
      "ActivitySources": {
        "Microsoft.AspNetCore": true,
        "System.Net.Http": true,
        "Experimental.*": false,
        "Diginsight.*": true,
        "SampleWebAPI": true
      },
      
      // Logging behavior control
      "LogBehavior": "Hide",
      "ActivityLogLevel": "Debug",
      
      // Activity-specific logging (pattern-based)
      "LoggedActivityNames": {
        "System.Net.Http|System.Net.Http.HttpRequestOut": "Hide",
        "Microsoft.AspNetCore.Hosting.HttpRequestIn": "Hide"
      }
    }
  }
}

Configuration Properties

ActivitySources - Dictionary controlling which activity sources are monitored: - Key: Activity source name pattern (supports wildcards *) - Value: true = monitor, false = ignore - Example: "MyApp.*": true monitors all activity sources starting with “MyApp.”

LogBehavior - Global default for activity logging (default: Hide): - Show: Log activity START and END events with full details - Hide: Don’t log activity events (activities still created for tracing/metrics) - Truncate: Log START but skip END events (minimal logging)

ActivityLogLevel - Log level for activity lifecycle events (default: Debug) - Standard .NET log levels: Trace, Debug, Information, Warning, Error, Critical - Note: When accessed via IDiginsightActivitiesLogOptions interface, this is exposed as LogLevel

LoggedActivityNames - Fine-grained control over specific activities: - Pattern-based dictionary overriding global LogBehavior - Supports source|operation pattern: "SourceName|OperationName": "Show" - Can be space-separated string: "Pattern1 Pattern2=Show Pattern3=Hide" - When accessed via IDiginsightActivitiesLogOptions interface, this is exposed as ActivityNames

Metric Recording Properties (optional - for OpenTelemetry integration): - RecordSpanDuration: Enable/disable span duration metric recording (default: false) - SpanDurationMeterName: OpenTelemetry meter name (e.g., “MyApp.Telemetry”) - SpanDurationMetricName: Metric name (default: “diginsight.span_duration”) - SpanDurationMetricDescription: Human-readable metric description

Other Properties: - WriteActivityActionAsPrefix: Include action (START/END) as prefix in logs (default: false) - DisablePayloadRendering: Disable rendering of activity payloads (default: false)

Pattern Matching Examples

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,              // All MyApp sources
        "MyApp.Orders.*": true,       // All Order-related sources
        "Microsoft.AspNetCore": true, // ASP.NET Core activities
        "System.*": false             // Skip all System activities
      },
      
      "LogBehavior": "Show",
      
      "LoggedActivityNames": {
        // Hide specific operations
        "System.Net.Http|System.Net.Http.HttpRequestOut": "Hide",
        "Microsoft.AspNetCore.Hosting.HttpRequestIn": "Hide",
        
        // Show only critical order operations
        "MyApp.Orders|ProcessOrder": "Show",
        "MyApp.Orders|CancelOrder": "Show",
        
        // Hide all internal operations
        "MyApp.Internal.*": "Hide",
        
        // Truncate health checks (start only, no end)
        "*|HealthCheck": "Truncate"
      }
    }
  }
}

Advanced Configuration with Metrics

If you want to enable metric recording (e.g., for later OpenTelemetry integration):

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,
        "Microsoft.AspNetCore": true
      },
      
      "LogBehavior": "Hide",
      "ActivityLogLevel": "Debug",
      
      // Metric recording configuration (optional)
      "RecordSpanDuration": false,  // Default: false for local-only scenarios
      "SpanDurationMeterName": "MyApp.Telemetry",
      "SpanDurationMetricName": "diginsight.span_duration",
      "SpanDurationMetricDescription": "Duration of application spans in milliseconds",
      
      "LoggedActivityNames": {
        "Microsoft.AspNetCore.Hosting.HttpRequestIn": "Hide",
        "MyApp.Orders.*": "Show"
      }
    }
  }
}

Note: For local console/file logging scenarios, you typically set RecordSpanDuration: false to avoid metric overhead. Enable metrics when integrating with OpenTelemetry (see Configure telemetry to remote tools).

String-Based Configuration (Alternative)

For LoggedActivityNames, you can also use a space-separated string format:

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true
      },
      
      "LogBehavior": "Hide",
      
      // Space-separated format
      "LoggedActivityNames": "MyApp.Orders.* MyApp.Payment.*=Show MyApp.Internal.*=Hide"
    }
  }
}

Format: "Pattern1 Pattern2=Behavior Pattern3=Behavior" - Pattern without =Behavior defaults to Show - Supported behaviors: Show, Hide, Truncate

Log Behavior Examples

Example 1: Show Everything (Development)

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,
        "Microsoft.AspNetCore": true,
        "System.Net.Http": true
      },
      "LogBehavior": "Show",
      "ActivityLogLevel": "Debug"
    }
  }
}

Result: All activities logged with full START/END details.

Example 2: Hide Framework, Show Business Logic (Production)

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,
        "Microsoft.AspNetCore": true,
        "System.Net.Http": true
      },
      "LogBehavior": "Hide",
      "LoggedActivityNames": {
        "MyApp.Orders.*": "Show",
        "MyApp.Payment.*": "Show",
        "Microsoft.AspNetCore.Hosting.HttpRequestIn": "Hide"
      }
    }
  }
}

Result: Only business-critical operations logged, framework activities hidden.

Example 3: Minimal Logging (High Performance)

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true
      },
      "LogBehavior": "Truncate",
      "LoggedActivityNames": {
        "MyApp.Orders.ProcessOrder": "Show"
      }
    }
  }
}

Result: Most activities show START only, critical operations show full START/END.

STEP 03 - Add telemetry to code with StartMethodActivity() and ILogger Statements

We are now ready to add instrumentation to the code and make the application flow observable.

The snippet below shows how to add telemetry to the GetWeatherForecast() method of the WeatherForecastController class:

[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get()
{
    // send method START and END events with Observability.ActivitySource
    using var activity = Observability.ActivitySource.StartMethodActivity(logger);

    var randomTemperature = Random.Shared.Next(-20, 55);
    // add to logger.LogDebug to send a log event
    logger.LogDebug("randomTemperature: {randomTemperature}", randomTemperature);

    var res = Enumerable.Range(1, 5).Select(index => new WeatherForecast
    {
        Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
        TemperatureC = randomTemperature,
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    }).ToArray();

    activity?.SetOutput(res);
    return res;
}

in the snippet above: - using var activity = Observability.ActivitySource.StartMethodActivity(logger); is added to provide observability of method start and end - logger.LogDebug("randomTemperature: {randomTemperature}", randomTemperature); is used to log the randomTemperature value during the method execution. - activity.SetOutput(result); is used to add the method result to the method END event.

How it works: 1. StartMethodActivity() creates an activity that: - Is checked against ActivitySources configuration to determine if it should be created - Follows the LogBehavior and LoggedActivityNames rules for logging - Automatically logs START event when created (if logging enabled) - Automatically logs END event when disposed (if logging enabled)

2. The activity’s logging behavior is determined by:
   • Global LogBehavior setting (Show/Hide/Truncate)
   • Specific patterns in LoggedActivityNames (overrides global)
   • Activity source must be enabled in ActivitySources

STEP 04 - run your code and look at the resulting application flow

The image below shows the application flow generated by DoSomeWork method.
The image below shows the sample method execution, where: - method start and end are logged with the Method name, - randomTemperature is logged as a standard variable value and - the method result is logged within the method END row.

alt text

STEP 03 (Full) - Add telemetry for the startup sequence

The S01_01_SampleWebAPIWithStartupSequence sample shows an example WebApi where telemetry is enabled also for the full startup sequence.

An ObservabilityManager is created with a LoggerFactory to record telemetry events until the ASP.NET Core Service Provider creation.
When the Service Provider is created, the recorded startup telemetry is sent to the configured registered providers (eg. Console, Log4Net).
In case of Exceptions during the startup sequence, telemetry is flushed to the Console/log4net by means of an emergency service provider, managed by the Observability manager.

public static void Main(string[] args)
{
    // this enables sending telemetry for the startup sequence
    // telemetry is recorded until ServiceProvider creation
    // after that, recorded telemetry is sent to the configured registered providers
    // (eg. AzureMonitor, Console, Log4Net) 
    using var observabilityManager = new ObservabilityManager();
    ILogger logger = observabilityManager.LoggerFactory.CreateLogger(typeof(Program));
    Observability.LoggerFactory = observabilityManager.LoggerFactory;

    WebApplication app;
    using (var activity = Observability.ActivitySource.StartMethodActivity(logger, new { args }))
    {
        var builder = WebApplication.CreateBuilder(args);
        var services = builder.Services;
        var configuration = builder.Configuration;
        var environment = builder.Environment;

        // Add logging and opentelemetry providers
        services.AddObservability(configuration, environment, out IOpenTelemetryOptions openTelemetryOptions);

        // registers recorded telemetry for flush after ServiceProvider creation
        observabilityManager.AttachTo(services);

        services.AddControllers();
        services.AddEndpointsApiExplorer();
        services.AddSwaggerGen();

        // use diginsight service provider 
        // this enables telemetry initialization at service provider creation
        builder.Host.UseDiginsightServiceProvider(true);
        app = builder.Build();

        if (app.Environment.IsDevelopment())
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.UseHttpsRedirection();

        app.UseAuthorization();

        app.MapControllers();
    }

    app.Run();
}

STEP 04 (Full) - run your code and look at the resulting application flow

The image below shows the application flow generated by the startup sequence.
In particular, Program.Main() method is logged with registration details of AddObservability() method.

Configuration Best Practices

Development Environment

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,
        "Microsoft.AspNetCore": true,
        "System.Net.Http": true
      },
      "LogBehavior": "Show",           // Show everything
      "ActivityLogLevel": "Debug"
    }
  }
}

Production Environment

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,
        "Microsoft.AspNetCore": true
      },
      "LogBehavior": "Hide",            // Default: hide
      "ActivityLogLevel": "Information",
      "LoggedActivityNames": {
        "MyApp.Orders.*": "Show",       // Show critical paths only
        "MyApp.Payment.*": "Show",
        "MyApp.Internal.*": "Hide"      // Explicitly hide internals
      }
    }
  }
}

Testing/Troubleshooting

{
  "Diginsight": {
    "Activities": {
      "ActivitySources": {
        "MyApp.*": true,
        "Microsoft.AspNetCore": true
      },
      "LogBehavior": "Truncate",        // START only
      "LoggedActivityNames": {
        "MyApp.Problematic.*": "Show"   // Full logging for problem area
      }
    }
  }
}

See Also

• Configure telemetry to remote tools - OpenTelemetry and metrics integration
• Use Dynamic Logging - Runtime configuration changes
• Class-Aware Configuration - Advanced per-class configuration