.Net Core SDK Guide

In this guide, you’ll learn how to integrate OpenTelemetry into your .NET application and install the APItoolkit SDK to enhance its functionalities. By combining OpenTelemetry’s robust tracing and metrics capabilities with the APItoolkit SDK, you’ll be able to monitor incoming and outgoing requests, report errors, and gain deeper insights into your application’s performance. This setup provides comprehensive observability, helping you track requests and troubleshoot issues effectively.

Prerequisites

Ensure you have already completed the first three steps of the onboarding guide.

Open Telemetry Setup

Setting up open telemetry allows you to send traces, metrics and logs to the APIToolkit platform. In this guid, we will be using the opentelemetry auto-instrumentation packages to setup open telemetry.

Install OpenTelemetry

Run the following command to install the OpenTelemetry auto instrumentation for .NET:

# Download the bash script
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Install core files
sh ./otel-dotnet-auto-install.sh

# Enable execution for the instrumentation script
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Setup the instrumentation for the current shell session
. $HOME/.otel-dotnet-auto/instrument.sh

See auto instrumentation setup for windows here.

OpenTelemetry Configuration

After installating .NET autoinstrumentation packages, you can configure the OpenTelemetry instrumentation by setting the following environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://otelcol.apitoolkit.io:4317" # Specifies the endpoint to send the traces to.
export OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES="APItoolkit.HTTPInstrumentation" # The apitoolkit instrumentation  activity resource.
export OTEL_SERVICE_NAME="my-service" # Specifies the name of the service.
export OTEL_RESOURCE_ATTRIBUTES="at-project-key={ENTER_YOUR_API_KEY_HERE}" # Adds your API KEY to the resource.
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc" # Specifies the protocol to use for the OpenTelemetry exporter.

After setting the environment variables, build and run your application and you should see the logs, traces and metrics in the APIToolkit dashboard.

APItoolkit SDK Configuration

After setting up open telemetry, you can now configure the apitoolkit middleware, to monitor incoming and outgoing requests, report errors, and gain deeper insights into your application's performance.

Installation

Kindly run the command below to install the SDK:

dotnet add package ApiToolkit.Net

Configuration

Next, initialize APItoolkit in your application's entry point (e.g., Program.cs), like so:

using ApiToolkit.Net;

// Initialize the APItoolkit client
var config = new Config
{
  ServiceVersion: "v2.0",
  ServiceName = "MyService",
};
var client = APIToolkit.NewClient(config);
// END Initialize the APItoolkit client

// Register APItoolkit's middleware
app.Use(async (context, next) =>
{
  var apiToolkit = new APIToolkit(next, client);
  await apiToolkit.InvokeAsync(context);
});
// END Register APItoolkit's middleware

app.MapGet("/hello", async context =>
{
  await context.Response.WriteAsync("Hello, world!");
});


app.Run();

In the configuration above you can add the following optional fields:

Redacting Sensitive Data

If you have fields that are sensitive and should not be sent to APItoolkit servers, you can mark those fields to be redacted (the fields will never leave your servers).

To mark a field for redacting via this SDK, you need to provide additional arguments to the config variable with paths to the fields that should be redacted. There are three arguments you can provide to configure what gets redacted, namely:

1. RedactHeaders: A list of HTTP header keys.
2. RedactRequestBody: A list of JSONPaths from the request body.
3. RedactResponseBody: A list of JSONPaths from the response body.

{
  "user": {
    "name": "John Martha",
    "email": "[email protected]",
    "addresses": [
      {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      }
    ],
    "credit_card": {
      "number": "4111111111111111",
      "expiration": "12/28",
      "cvv": "123"
    }
  }
}

Examples of valid JSONPath expressions would be:

Here's an example of what the configuration would look like with redacted fields:

using ApiToolkit.Net;

var config = new Config
{
  RedactHeaders = new List<string> { "content-type", "Authorization", "HOST" },
  RedactRequestBody = new List<string> { "$.user.email", "$.user.addresses" },
  RedactResponseBody = new List<string> { "$.users[*].email", "$.users[*].credit_card" }
};
var client = APIToolkit.NewClient(config);

// Register the middleware to use the initialized client
app.Use(async (context, next) =>
{
  var apiToolkit = new APIToolkit(next, client);
  await apiToolkit.InvokeAsync(context);
})

Error Reporting

APItoolkit automatically detects different unhandled errors, API issues, and anomalies but you can report and track specific errors at different parts of your application. This will help you associate more detail and context from your backend with any failing customer request.

To manually report specific errors at different parts of your application, use the ReportError() handler, passing in the context and error arguments, like so:

using ApiToolkit.Net;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var config = new Config
{
  ServiceName = "Backend"
};
var client = APIToolkit.NewClient(config);

app.Use(async (context, next) =>
{
  var apiToolkit = new APIToolkit(next, client);
  await apiToolkit.InvokeAsync(context);
});

app.MapGet("/error-tracking", async context =>
{
  try
  {
    // Attempt to open a non-existing file
    using (var fileStream = System.IO.File.OpenRead("non_existing_file.txt"))
    {
      // File opened successfully, do something if needed.
    }
    await context.Response.WriteAsync($"Hello");
  }
  catch (Exception error)
  {
    // Report the error to APItoolkit
    client.ReportError(context, error);
    await context.Response.WriteAsync("Error reported!");
  }
});

Monitoring Outgoing Requests

Outgoing requests are external API calls you make from your API. By default, APItoolkit monitors all requests users make from your application and they will all appear in the API Log Explorer page. However, you can separate outgoing requests from others and explore them in the Outgoing Integrations page, alongside the incoming request that triggered them.

To monitor outgoing HTTP requests from your application, we provide the APIToolkitObservingHandler() handler. Here's an example of the outgoing requests configuration with this SDK on a sample /monitor-requests endpoint that makes an asynchronous HttpClient GET request to a sample public endpoint URL.

using ApiToolkit.Net;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var config = new Config
{
  ApiKey = "{ENTER_YOUR_API_KEY_HERE}"
};
var client = APIToolkit.NewClient(config);

app.Use(async (context, next) =>
{
  var apiToolkit = new APIToolkit(next, client);
  await apiToolkit.InvokeAsync(context);
});

app.MapGet("/monitor-requests", async (context) =>
{
  var observingHandlerOptions = new ATOptions
  {
    PathWildCard = "/posts/{id}",
    RedactHeaders = ["User-Agent"],
    RedactRequestBody = ["$.user.password"],
    RedactResponseBody = ["$.user.data.email"]
  };

  using var httpClient = new HttpClient(client.APIToolkitObservingHandler(context, observingHandlerOptions));
  var response = await httpClient.GetAsync("https://jsonplaceholder.typicode.com/posts/1");
  var body = await response.Content.ReadAsStringAsync();
  await context.Response.WriteAsync(body);
});

The client.APIToolkitObservingHandler handler accepts a required context field and the following optional fields: