DEV Community: Matt Hosking

Analysing a .NET Codebase with Roslyn

Matt Hosking — Sun, 13 Jun 2021 13:08:53 +0000

But Why Would I Want To Do This?

When you're dealing with a complex system, particularly one with a lot of interconnections (such as a microservice architecture), it can be very useful to extract and even visualise metadata about those connections. You may also want to assess the usage of a particular NuGet package, or where that critical helper class is actually used. You can certainly do all of this with Visual Studio itself, or even more effectively with ReSharper, but what if you then want to drill down further or extract the data about the usages to document or visualise some how? This is where using the Roslyn compiler can be very handy.

What Is Roslyn?

Roslyn is the open-source implementation of both the C# and Visual Basic compilers with an API surface for building code analysis tools.

To give you an idea of how it works and what it's capable of, have a look at the .NET Compiler Platform SDK model. Essentially, you can use .NET to analyse .NET code, representing all the metadata about types, usages and structure as objects. You can load a single file, a project or even a whole solution. This is all provided through a series of NuGet packages, some that leverage the MSBuild libraries.

Getting Started

The key NuGet package you'll need is Microsoft.CodeAnalysis. You can use Microsoft.CodeAnalysis.CSharp.Workspaces if you don't need Visual Basic support (does anyone really these days?) This will allow you to do everything with C# (.cs) files, but you'll likely also want to load C# projects (.csproj) and solution (.sln) files. For this you'll need Microsoft.CodeAnalysis.Workspaces.MSBuild. This has a dependency on Microsoft.Build, so also add a direct reference on this so it uses the latest (it defaults to 15.3 at time of writing, where 16.10 is latest). Don't worry about the restored using .NETFramework warning - it uses the binaries at runtime separately. Finally, you'll need Microsoft.Build.Locator, so your existing Visual Studio build tools can be used (or you'll promptly get a cryptic error at runtime).

Loading a Solution

The very first thing you'll need in your code looks like this:



if (!MSBuildLocator.IsRegistered)
{
  var instances = MSBuildLocator.QueryVisualStudioInstances().ToArray();
  MSBuildLocator.RegisterInstance(instances.OrderByDescending(x => x.Version).First());
}

This will find all .NET Core SDKs (including .NET 5+) and use the latest version. Feel free to change the logic for which version to use to suit your needs (if you don't want the latest version installed). Next you need to create an MSBuildWorkspace to load your solution into:



var workspace = MSBuildWorkspace.Create();
workspace.SkipUnrecognizedProjects = true;
workspace.WorkspaceFailed += (sender, args) =>
{
  if (args.Diagnostic.Kind == WorkspaceDiagnosticKind.Failure)
  {
    Console.Error.WriteLine(args.Diagnostic.Message);
  }
};

I use SkipUrecognizedProjects for those cases where you are using non C# projects mixed in (like anything kind of database or deployment project). The WorkspaceFailed handler is to log any issues that occur, as it will silently fail with no loaded documents or projects, depending on the error, without this. Now you can load the solution:



var solution = await workspace.OpenSolutionAsync(@"C:\Dev\MyDevThing\MySolution.sln", new ProgressBarProjectLoadStatus());

public class ProgressBarProjectLoadStatus : IProgress<ProjectLoadProgress>
{
  public void Report(ProjectLoadProgress value)
  {
    Console.Out.WriteLine($"{value.Operation} {value.FilePath}");
  }
}

The OpenSolutionAsync requires the file name, but also a class that implements IProgress. I've provided a simple console output implementation here.

Working With a Project

It's pretty easy to get the project you want from the solution with something like:



var project = solution.Projects.SingleOrDefault(x => string.Equals(x.Name, projectName, StringComparison.OrdinalIgnoreCase))

But what next? First you'll want to get a compilation context, as this is required for a lot of actions you may want to perform:



var compilation = await project.GetCompilationAsync();

Once you have this, retrieving any type that would be visible in the context of this project is as simple as:



var typeSymbol = compilation.GetTypeByMetadataName(typeName);

Find Usages of a Type

For this kind of scenario, the static class, SymbolFinder, is provided. Have a look at the documentation for it to see all the functionality it provides. Here is an example of finding usages of an interface



var typeSymbol = compilation.GetTypeByMetadataName("MyNamespace.IMyInteface");
await SymbolFinder.FindImplementationsAsync(typeSymbol, solution)

Working With Files

This needs to be the full name of the type (although you won't usually need Assembly information) and for generics, you'll need to use the MyType`1 syntax (`1 indicates one type parameter, `2 is two, etc.). To load a file is easy as well:



var document = _project.Documents.Single(x => x.Name == fileName);
var syntaxRoot = await document.GetSyntaxRootAsync();
var semanticModel = await document.GetSemanticModelAsync();

The first line speaks for itself, and the syntax root and semantic model are used for analyzing the document syntax and symbols, respectively. For example, to find a method in a file, then find all usages of that method in your solution:



var methodDeclaration = syntaxRoot.DescendantNodes().OfType<MethodDeclarationSyntax>().Single(x => x.Identifier.Text == methodName);
var semanticModel = compilation.GetSemanticModel(methodDeclaration .SyntaxTree);
var methodSymbol = semanticModel.GetDeclaredSymbol(methodDeclaration);
var callers = await SymbolFinder.FindCallersAsync(methodSymbol, solution);

Or the same for a property in that file:



var propertyDeclaration = syntaxRoot.DescendantNodes().OfType<PropertyDeclarationSyntax>().Single(x => x.Identifier.Text == propertyName);
var semanticModel = compilation.GetSemanticModel(propertyDeclaration.SyntaxTree);
var methodSymbol = semanticModel.GetDeclaredSymbol(propertyDeclaration);
var callers = await SymbolFinder.FindCallersAsync(propertySymbol, solution);

I find a great way to discover the class I'm after, is either to set a breakpoint and dig through the syntax root in the debugger, or explore the C# syntax namespace. From your found syntax instance, you then need the semantic model to find the symbol that relates to it. For this you can use GetDeclaredSymbol or GetSymbolInfo (see here for a good explanation on when to use which). This symbol is then something which has global meaning across your solution (as opposed to a syntax, which is just code in a file), and can therefore be used with the SymbolFinder class.

Where to Next?

There's plenty you can do with the calls you find with SymbolFinder and a lot more analysis you could perform. I highly recommend you take a look at the supporting source code to get some ideas (analyses itself).

GraphQL.NET with ASP.NET Integration Tests

Matt Hosking — Sun, 30 May 2021 13:02:43 +0000

Supporting code available on GitHub.

ASP.NET Integration Tests

Microsoft have created a really effective way to perform unit tests against the closest thing to a server hosting your deployed code. Don't let the name throw you, though - these tests integrate your code modules together for testing, but aren't integrated to external resources (such as database, APIs or other services). This means that some level of mocking will still be required, but with the benefit that your entire solution (start up process, API end points, serialization, etc.) will be included in the test. It's certainly not as granular as a unit test would normally be, and I'd highly recommend those for testing complex logic, but it's a very useful tool for a higher layer of tests.

Setting Up the Test Server

The simplest way to get running is to use the WebApplicationFactory class and set it up as an xUnit class fixture. This gives you a class like this:

public class GraphQLTests : IClassFixture<WebApplicationFactory<Startup>>
{
  private readonly WebApplicationFactory<Startup> _factory;

  public GraphQLTests(WebApplicationFactory<Startup> factory)
  {
    _factory = factory;
  }

  ...
}

Where Startup is the existing class you use in your main program. From there, you can simply call _factory.CreateClient to give you your HttpClient for testing.

Mocking Dependencies

It's fairly simple to mock interfaces for your services dependent on external APIs and the like, but ideally you would mock only the communication layer and leave all the other service business logic in the test. For Entity Framework, this has an in-memory database provider which is brilliant for this sort of thing. You can seed data up front (in your Arrange phase), let your code perform modifications (in the Act phase) and then verify everything is how you expect it to be (in the Assert phase). So how do you modify your service set up without having to create a new Startup class or have a whole lot of virtuals and overrides in a test class? The WebApplicationFactory class provides the following method to do exactly that:

var factory = _factory.WithWebHostBuilder(builder =>
{
  builder.ConfigureServices(services =>
  {
    services.Replace(ServiceDescriptor.Singleton<IDocumentExecuter, OptimisedDocumentExecuter>());
  });
});

This creates a new factory that applies the additional configuration (in this case, additional service configuration).

Executing GraphQL Queries

The integration test server allows you to create a HttpClient that has a special HttpMessageHandler that, rather than using TCP sockets, communicates directly with the in-memory server. All the usual serialisation still occurs. We can very easily use this to execute a GraphQL query, manually forming a HttpRequestMessage, but to make things a little easier, we can use GraphQL.NET's GraphQL.Client package. With this in play, we can create a simple test using the HttpClient we created earlier:

var graphClient = new GraphQLHttpClient(new GraphQLHttpClientOptions { EndPoint = new Uri("http://localhost/api/graphql") }, new SystemTextJsonSerializer(), httpClient);

var response = await graphClient
  .SendQueryAsync(@"query TestQuery($id: String!) {
  droid(id: $id) {
    id
    name
  }
}",
  new
  {
      id = "3"
  }, "TestQuery", () => new { droid = new DroidResponse() });

response.Errors.Should().BeNullOrEmpty();
response.Data.droid.Name.Should().Be("R2-D2");

I highly recommend you read the GraphQL.Client docs, but the short of it is that you provide the query, variables and operation name (fairly straight-forward), with a final parameter that specifies the "shape" of the the response. This shape provides the structure to use when deserializing the response. Finally I'm using Fluent Assertions to validate some properties of the response.

Integrating Apollo Studio with GraphQL for .NET - Part 3

Matt Hosking — Sat, 29 May 2021 07:39:31 +0000

Setting Up Apollo Studio

Now that we have code to push metrics, we need to set up Apollo Studio and get our API key. Navigate to Apollo Studio and create a free account. You'll need to add a new graph - be sure to select "Deployed" as "Development" doesn't support reporting of query metrics.

Uploading Your Schema

Now that we have an account and Graph, we'll need to upload our schema. The easiest way to get started is to do a manually triggered introspection of your local server:

Make sure you include "/api/graphql" in your URL. Once this is uploaded, you'll have access to a number of tabs - go to the "Schema" tab. From there, the first thing you'll need is the "Graph Ref". This is used as an input to the GraphQL trace logger we created in the earlier articles:

Creating an API Key

From the "Settings" tab, if you scroll down you can see the "API Keys" section. Create a new key (name is optional) and you'll be provided with an API key. As per usual with API keys, if you don't copy it somewhere, you won't be able to get it back and you'll have to delete the key and create a new one.

This API key is the other setting required by the trace uploader.

Using the Trace Logger

Presuming you have your background service running, all you need is to register the trace logger in a way that provides these values. You can see how this has been done in the GitHub supporting code. Since the signature for the constructor is:

ApolloReportingTraceLogger(IHttpClientFactory httpClientFactory, ISchema schema, string apiKey, string graphRef, ILogger<ApolloReportingTraceLogger> logger)

I like to register it as follows:

services.AddSingleton<IGraphQLTraceLogger>(provider =>
  ActivatorUtilities.CreateInstance<ApolloReportingTraceLogger>(provider, Configuration["ApolloStudio:ApiKey"], Configuration["ApolloStudio:GraphRef"])
);

This approach will automatically resolve IHttpClientFactory (provided you have used services.AddHttpClient()), ISchema and the ILogger from DI and use the first string as apiKey and the second as graphRef. Then all you need is the following setting in your appsettings.json file, with an override for your appsettings.Development.json for your local dev values (so you don't accidentally commit them to source, you should have the development version in .gitignore).

  "ApolloStudio": {
    "ApiKey": "",
    "GraphRef": ""
  }

Testing It Out!

Now that we have everything hooked up, we should be able to run a query and have it show in the Apollo Studio UI. Run your solution, and execute a query. In Apollo Studio, open the "Operations" tab and keep refreshing. After 30 seconds or so, your query should appear:

You can get general performance statistics for your queries, but the features to break down errors and drill down into resolver-level performance is reserved for the paid version. Team version (at time of writing) is USD$59/mth per user (you can have unlimited read only users for free, though), or USD$49/mth if paid annually. There's a 14 day trial, which I've used to generate resolver level stats for my sample below:

Improving the GraphQL.NET Data Loader Execution Strategy

Matt Hosking — Fri, 28 May 2021 13:04:30 +0000

UPDATE 29/05/2021: Added supporting code on GitHub.
UPDATE 30/05/2021: Added support for interface types.

Improving GraphQL Performance

When using any GraphQL implementation, a key issue that crops up rather quickly is poor performance due to inefficient execution of the back end implementation. For simple CRUD queries, resolvers generally don't have many issues. Once we start retrieving lists of data and/or complex hierarchies, it's critical that the data loader
is used effectively. This will ensure that all resolvers queue their requests to whatever back-end implementation they use (typically database or APIs) so that they can efficiently retrieve the data.

How the Data Loader Operates

The data loader is used to queue execution nodes to be resolved, which are then executed using the defined execution strategy, unblocking further data loaders, then repeating the process. The problem with the default execution strategy (parallel), is that the order the pending nodes are executed in is not optimal for unblocking other nodes that could become part of an existing batch.

Example

You are retrieving all customers, including their addresses, which in turn includes their suburbs
As part of this query you also want to include "suburb of work" (hypothetical to suit this scenario, but think of it as a limited data collection).
You execute the query and the following happens:
1. The customer retrieval is queued.
2. Since there is no data to act on until this is retrieved, this node is executed before continuing.
3. The address retrieval is batched for all customers (presumably using a batch address retrieval REST API or SQL query) and the suburb retrieval is batched for all customers. The address suburbs are blocked by address retrieval so they are not batched.
4. Address retrieval and suburb retrieval is executed.
5. Now that addresses are available, suburbs can be batched for them.
6. Suburb retrieval is again executed.

The problem here is that were we to retrieve all addresses, then check again, we could execute one suburb retrieval. The problem expands in more complex scenarios and in one query I had, this meant 45 queries instead of 23.

Changing the Default Strategy

The execution strategy selection is performed by the registered instance for IDocumentExecuter. The easiest way to customise this is to create a class derived from DocumentExecuter and override the SelectExecutionStrategy method:

public class OptimisedDocumentExecutor : DocumentExecuter
{
  protected override IExecutionStrategy SelectExecutionStrategy(ExecutionContext context)
  {
    return context.Operation.OperationType == OperationType.Query
      ? new PrioritisedParallelExecutionStrategy()
      : base.SelectExecutionStrategy(context);
  }
}

Modifying the Parallel Execution Strategy

Extract the Data Loader Execution

Customising the default ParallelExecutionStrategy is harder though. The best way to achieve this is to take the existing source code and modify it. The key section we need to modify is the last part of the try/catch in ExecuteNodeTreeAsync:

//run pending data loaders
while (pendingDataLoaders.Count > 0)
{
  var dataLoaderNode = pendingDataLoaders.Dequeue();
  currentTasks.Add(CompleteDataLoaderNodeAsync(context, dataLoaderNode));
  currentNodes.Add(dataLoaderNode);
}

First we move this to its own method that takes all required context, with an additional pendingDataLoaders list of execution nodes:

private void ProcessDataLoaders(Queue<ExecutionNode> dataLoaderQueue, ExecutionContext context, List<Task> currentTasks, List<ExecutionNode> currentNodes, List<ExecutionNode> pendingDataLoaders)
{
  while (dataLoaderQueue.Count > 0)
  {
    var dataLoaderNode = dataLoaderQueue.Dequeue();
    pendingDataLoaders.Remove(dataLoaderNode);
    currentTasks.Add(CompleteDataLoaderNodeAsync(context, dataLoaderNode));
    currentNodes.Add(dataLoaderNode);
  }
}

Prioritise Blocking Data Loaders

Next we need to change the logic to ensure data loaders that are blocking other data loaders are always processed first. First, change the type of the pendingDataLoaders class to List<ExecutionNode>, which will also require you to change the following (occurs twice) from Enqueue to Add:

if (pendingNode.Result is IDataLoaderResult)
{
  pendingDataLoaders.Enqueue(pendingNode);
}

Then replace the original "run pending data loaders" while loop from above (now that it is moved out to a method) with the following:

var pendingLoaderGraphTypes = pendingDataLoaders
    .Select(x => GetGraphTypes(x)?.Name)
    .Where(x => x != null)
    .ToHashSet();

// always process priority data loaders first as they potentially block others that can be batched in
var priorityDataLoaders = new Queue<ExecutionNode>(pendingDataLoaders
    .Where(x => HasChildOfGraphType(x, context, pendingLoaderGraphTypes))
);

var remainingDataLoaders = new Queue<ExecutionNode>(pendingDataLoaders
    .Except(priorityDataLoaders)
);

if (priorityDataLoaders.Count > 0)
{
    ProcessDataLoaders(priorityDataLoaders, context, currentTasks, currentNodes, pendingDataLoaders);
    continue;
}

//run pending data loaders
ProcessDataLoaders(remainingDataLoaders, context, currentTasks, currentNodes, pendingDataLoaders);

This has the following flow:

Get the graph type related to all pending data loaders.
Get all the pending data loaders that have a child in the query of a pending loader graph type. These become the "priority" data loaders.
If there are any priority loaders identified, process them first using the extracted method, then restart the flow.
If there were no priority loaders, process any remaining data loaders. This ensures that any priority loaders continue to be processed until none can be identified, then resolve the rest.

Resolving Graph Types for Execution Nodes

I derived the following from GraphQL.NET source:

private static IObjectGraphType[] GetGraphTypes(ExecutionNode executionNode)
{
  IGraphType? graphType = null;
  switch (executionNode)
  {
    case ValueExecutionNode:
      return Array.Empty<IObjectGraphType>();
    case ObjectExecutionNode objectNode:
      graphType = objectNode.GraphType;
      break;
    case ArrayExecutionNode arrayNode:
      {
        graphType = ((ListGraphType)arrayNode.GraphType).ResolvedType;
        break;
      }
  }

  if (graphType is NonNullGraphType nonNullGraphType)
    graphType = nonNullGraphType.ResolvedType;

  return graphType switch
  {
    IInterfaceGraphType interfaceGraphType => interfaceGraphType.PossibleTypes.ToArray(),
    IObjectGraphType objectGraphType => new[] { objectGraphType },
    _ => Array.Empty<IObjectGraphType>()
  };
}

It assumes for a pending data loader that it is either an array or an object. For an object we can retrieve the graph type using GetObjectGraphType. For the array type we need to identify the item type. This will be the resolved type for the list.

Determining if a Node Has a Sub Type

The following was also determined from GraphQL.NET source internals:

private bool HasChildOfGraphType(ExecutionNode executionNode, ExecutionContext context, ISet<string> searchGraphTypes)
{
  var graphTypes = GetGraphTypes(executionNode);
  if (graphTypes.Length == 0)
    return false;

  return graphTypes
    .Any(graphType => CollectFieldsFrom(context, graphType, executionNode.Field?.SelectionSet, null)
      .Select(x => new
      {
        Field = x.Value,
        FieldDefinition = GetFieldDefinition(context.Schema, graphType, x.Value)
      })
      .Select(x => BuildExecutionNode(executionNode, x.FieldDefinition.ResolvedType, x.Field, x.FieldDefinition))
      .Any(x => GetGraphTypes(x).Any(t => searchGraphTypes.Contains(t.Name)) || HasChildOfGraphType(x, context, searchGraphTypes))
    );
}

This requires a newer version of GraphQL.NET, as previously the ExecutionHelper provided CollectFields and GetFieldDefinition.
This is derived from the source from the parent ExecutionStrategy class' SetSubFieldNodes method, as this takes an execution context and node and expands the selection set from the query into the AST fields, retrieves each field's definition and builds execution nodes. From those child execution nodes, you can determine graph types, allowing you to determine if the query selection has a pending data loader type.

Integrating Apollo Studio with GraphQL for .NET - Part 2

Matt Hosking — Fri, 28 May 2021 10:22:23 +0000

In the previous article, I covered some of the challenges of supporting a GraphQL implementation, and how to begin integration to Apollo Studio via their protobuf interface. The supporting code is available on GitHub as mattjhosking/graphql-dotnet-apollo-studio.

Creating a Client

The first thing we need is an interface for our client, for DI and unit testing:

public interface IGraphQLTraceLogger
{
  void LogTrace(HttpContext httpContext, string? operationName, string? query, ExecutionResult result);
  AsyncAutoResetEvent ForceSendTrigger { get; }
  Task Send();
}

The LogTrace method takes the HttpContext (for retrieving headers), operation name and query (for determining the request hash, more on this later) and the execution result containing the Apollo tracing information. Send simply sends all queued traces to Apollo Studio and ForceSendTrigger allows overriding the delay between sending batches. Details on AsyncAutoResetEvent can be found in this Microsoft Dev blogs article.

Creating a Trace

First, we need to convert the execution result to the Trace object using the metrics to trace converter from the previous article. If this succeeds, then we set the trace ClientName using a specified header ("apollographql-client-name", with fallback to first portion of "User-Agent") and ClientVersion with another header ("apollographql-client-version", with fallback to second portion of "User-Agent").

Grouping Traces

Each trace must be grouped by the operation and query. The way Apollo works with this is to use the format:
# {operationName}
{query}
Operation name is the GraphQL operation name and the query is the entire query with whitespace reduced. I used the following method:

private static string MinimalWhitespace(string? requestQuery)
{
  return Regex.Replace((requestQuery ?? "").Trim().Replace("\r", "\n").Replace("\n", " "), @"\s{2,}", " ");
}

Thread Safety

Since the trace logger needs to be thread-safe, a lock is required when accessing the traces:

private const int BATCH_THRESHOLD_SIZE = 2 * 1024 * 1024; 
...
lock (_tracesLock)
{
  var tracesAndStats = _traces.GetOrAdd($"# {(string.IsNullOrWhiteSpace(operationName) ? "-" : operationName)}\n{MinimalWhitespace(query)}", key => new TracesAndStats());
  tracesAndStats.Traces.Add(trace);

  // Trigger sending now if we exceed the batch threshold size (2mb)
  if (Serializer.Measure(CreateReport(_traces)).Length > BATCH_THRESHOLD_SIZE)
      ForceSendTrigger.Set();
}

The GetOrAdd retrieves the existing TracesAndStats grouping for this query (if any traces exist since the last batch was sent) or creates a new one. We then add the current trace to this grouping. Next, the protobuf Serializer static class can be used to measure how many bytes a report would be if we sent the current queued batch. If it exceeds the batch size threshold (2mb, as per recommended by Apollo Studio), then we set the ForceSendTrigger to override the delay (more on this later). CreateReport will be defined in the next section.

Sending to Apollo Studio

The Send method is responsible for taking all queued traces and dispatching via HTTP to the Apollo Studio servers.

Thread Safety

In order to ensure that the traces field is not modified while we're processing it, we need to swap its value with a new, empty dictionary. The best way to do this (and the only way to do it atomically) is to use Interlocked.Exchange. This does exactly what we require, all in one operation that no thread execution can get in the middle of (and consequently explode).

IDictionary<string, TracesAndStats> traces;
lock (_tracesLock)
  traces = Interlocked.Exchange(ref _traces, new ConcurrentDictionary<string, TracesAndStats>());

Creating the Report

We first need to create the full report with all traces before we can send. The CreateReport method mentioned earlier creates an instance of the Report class, with a static header. I initialise this as follows:

_reportHeader = new ReportHeader
{
  Hostname = Environment.GetEnvironmentVariable("WEBSITE_HOSTNAME") ?? Environment.MachineName,
  AgentVersion = "engineproxy 0.1.0",
  ServiceVersion = Assembly.GetExecutingAssembly().FullName,
  RuntimeVersion = $".NET Core {Environment.Version}",
  Uname = Environment.OSVersion.ToString(),
  GraphRef = graphRef,
  ExecutableSchemaId = ComputeSha256Hash(new SchemaPrinter(schema).Print())
};

Hostname uses either the Azure app service host name or the current machine name.
Agent version I've set to the same value the NodeJS version of the reporting client uses.
Service version is set as the full assembly details.
Runtime version is the version of .NET Core in use (this really should factor in that 5.0 is not "Core").
Uname is OS version.
Graph ref is provided by configuration as the graph name registered in Apollo Studio combined with the version in use, separated by an '@'.
Executable schema ID is determined by computing a SHA256 hash on the full schema (SchemaPrinter utility from GraphQL.Utilities used for this). The hash is calculated as follows:

private static string ComputeSha256Hash(string rawData)
{
  using SHA256 sha256Hash = SHA256.Create();
  byte[] bytes = sha256Hash.ComputeHash(Encoding.UTF8.GetBytes(rawData));
  StringBuilder builder = new StringBuilder();
  foreach (var t in bytes)
    builder.Append(t.ToString("x2"));
  return builder.ToString();
}

This performs a straight-forward SHA256 hash and then converts the resulting bytes to hex.

Preparing the Message

It's pretty straight-forward to follow the protobuf-net docs to serialize the report, but we should really GZIP the stream for sending to reduce bandwidth consumption and improve performance:

byte[] bytes;
await using (var memoryStream = new MemoryStream())
{
  await using (var gzipStream = new GZipStream(memoryStream, CompressionLevel.Fastest))
    Serializer.Serialize(gzipStream, report);
  bytes = memoryStream.ToArray();
}

We're using the fastest compression level here to minimise CPU load. The GZipStream is part of System.IO.Compression and wraps a writable stream for compression when writing to the underlying stream. I'm using a MemoryStream as we have no need to store this anywhere (nor should we). The remainder is fairly simply:

var httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, new Uri("https://engine-report.apollodata.com/api/ingress/traces"));
httpRequestMessage.Headers.Add("X-Api-Key", _apiKey);

httpRequestMessage.Content = new ByteArrayContent(bytes)
{
  Headers =
  {
    ContentType = new MediaTypeHeaderValue("application/protobuf"),
    ContentEncoding = {"gzip"}
  }
};

var client = _httpClientFactory.CreateClient();
var response = await client.SendAsync(httpRequestMessage);
if (!response.IsSuccessStatusCode)
  _logger.LogWarning("Failed to send traces to Apollo Studio with error code {errorCode}", response.StatusCode);

Of note are the media type of "application/protobuf" and the content encoding set as "gzip". The "X-Api-Key" header is the standard authentication mechanism they use and the URL is fixed (no other servers exist).

Periodic Send of Batches

So after we've put this all together, nothing is sending since nothing is actually calling the Send method. We now need to create a class derived from BackgroundService and override the ExecuteAsync as follows:

while (!stoppingToken.IsCancellationRequested)
{
  using (var scope = _serviceProvider.CreateScope())
  {
    var graphQlTraceLogger = scope.ServiceProvider.GetRequiredService<IGraphQLTraceLogger>();

    // Send every 20 seconds or when forced due to size threshold reached
    var nextExecution = DateTime.Now.AddSeconds(20);
    await Task.WhenAny(graphQlTraceLogger.ForceSendTrigger.WaitAsync(), Task.Delay(Math.Max((int)(nextExecution - DateTime.Now).TotalMilliseconds, 0), stoppingToken));

    _logger.LogDebug("Sending queued traces...");
    await graphQlTraceLogger.Send();
  }
}

We don't strictly need to create a scope in the service provider as the service itself is singleton (and therefore our trace logger must be), but it's good practice to resolve your classes from a scope in a background service. You can also see for the ForceSendTrigger comes into it here - it can override the 20 second wait and send immediately. The reason for doing this all centrally is to avoid a race condition where multiple sends could happen at once. This approach completely eliminates that possibility.

Up Next

This article now gives you a completely working approach to sending traces to Apollo Studio from a GraphQL.NET implementation, but we haven't looked at how we configure that or how they'll appear. The last article in this series will cover those points.

Integrating Apollo Studio with GraphQL for .NET - Part 1

Matt Hosking — Thu, 27 May 2021 10:27:58 +0000

GraphQL can be an incredibly useful tool for decoupling orchestration and schema for your back end implementation, be it APIs, direct database calls or even a simple in-memory store. One thing that presents itself fairly quickly, though, is the issue of tracking what is happening when your Graph queries are executed.

Query Issues

Adding an additional layer presents an entirely new suite of issues to address, the most common of which below.

Number of IO Operations

A single Graph query can look deceptively simple, but be configured to call many APIs, read / write to many areas of a data store or even call out to third party providers. This can occur due to an overly complicated back-end implementation, or simply pulling too much data from the front end.

Overall Duration (Performance)

Often this can be a side-effect of the above, but one IO operation can be all it takes to drag a query down. That one API call, which runs a poorly optimized SQL query can take 30+ seconds given the right conditions or data set.

Errors

Logging is incredibly helpful for tracking your errors, but for viewing statistics on the queries generating errors and individual traces, this can be a more complex task to generate from logs.

Monitoring Your Setup

Apollo GraphQL is a very common community-driven GraphQL implementation, primarily for NodeJS. In addition to the core libraries, they offer a free (with paid additional functionality available) SaaS platform for monitoring your GraphQL implementation: Apollo Studio. This offers solutions to the above, as well as the following functionality:

Track schema changes (with notifications)
Explore your schema and run queries
Report on schema usage

Integrating to Apollo Studio

For users of the Apollo Server GraphQL implementation (for NodeJS), it's pretty straight-forward. For Java and Python implementations there are also third-party providers, but that's where support ends. The link above also details how to create a custom integration and that's where this article picks up. This process involves: importing the protobuf schema, converting performance stats to Apollo trace format, signing the message and finally converting to a background process for batching.

Generating Apollo Studio Classes for Protobuf

There are a number of Protobuf implementations for .NET Core, but I like protobuf-net as it's a nice, clean, Apache 2.0 Licensed implementation. It is also supported by protogen, a great online generator that will output protobuf-net classes ready for use (for its CSharp profile). If you open the latest schema from the link here, you can simply paste into the generator.

NOTE: At the time of writing, [(js_preEncoded)=true] isn't supported by the generator, and can be removed from the proto schema.

Converting to Apollo Studio Format

In order to get data in a suitable format for Apollo, you can enable Apollo Tracing enrichment of your responses in GraphQL.NET. What follows is a large code dump of how I put together a conversion system for these classes to those generated by the above:

public class MetricsToTraceConverter
{
  public Trace? CreateTrace(ExecutionResult result)
  {
    ApolloTrace? trace = result.Extensions != null && result.Extensions.ContainsKey("tracing") ? (ApolloTrace)result.Extensions["tracing"] : null;

    var resolvers = trace?.Execution.Resolvers?
      .OrderBy(x => string.Join(":", x.Path), new ConfigurationKeyComparer())
      .ToArray();

    var rootTrace = resolvers?.FirstOrDefault(x => x.Path.Count == 1);
    if (rootTrace == null && result.Errors == null)
      return null;

    int resolverIndex = 1;
    var rootErrors = result.Errors?.Where(x => x.Path != null && x.Path.Count() == 1).ToArray();

    var rootNode = rootTrace != null && resolvers != null
      ? CreateNodes(rootTrace.Path, CreateNodeForResolver(rootTrace, rootErrors), resolvers, ref resolverIndex, GetSubErrors(rootTrace.Path, result.Errors?.ToArray()))
      : new Trace.Node();

    if (rootTrace == null && result.Errors != null)
    {
      foreach (var executionError in result.Errors)
        rootNode.Errors.Add(CreateTraceError(executionError));
    }

    return new Trace
    {
      StartTime = trace?.StartTime ?? DateTime.Now,
      EndTime = trace?.EndTime ?? DateTime.Now,
      DurationNs = (ulong)(trace?.Duration ?? 0),
      http = new Trace.Http { method = Trace.Http.Method.Post, StatusCode = result.Errors?.Any() == true ? (uint)HttpStatusCode.BadRequest : (uint)HttpStatusCode.OK },
      Root = rootNode
    };
  }

  private static Trace.Node CreateNodeForResolver(ApolloTrace.ResolverTrace resolver, ExecutionError[]? executionErrors)
  {
    var node = new Trace.Node
    {
      ResponseName = resolver.FieldName,
      Type = resolver.ReturnType,
      StartTime = (ulong)resolver.StartOffset,
      EndTime = (ulong)(resolver.StartOffset + resolver.Duration),
      ParentType = resolver.ParentType
    };

    if (executionErrors != null)
    {
      foreach (var executionError in executionErrors)
        node.Errors.Add(CreateTraceError(executionError));
    }

    return node;
  }

  private static Trace.Error CreateTraceError(ExecutionError executionError)
  {
    var error = new Trace.Error
    {
      Json = JsonConvert.SerializeObject(executionError),
      Message = executionError.Message
    };
    if (executionError.Locations != null)
      error.Locations.AddRange(executionError.Locations.Select(x => new Trace.Location { Column = (uint)x.Column, Line = (uint)x.Line }));
    return error;
  }

  private static ExecutionError[]? GetSubErrors(List<object> path, ExecutionError[]? errors)
  {
    return errors
      ?.Where(x => x.Path != null && x.Path.Count() > path.Count && x.Path.Take(path.Count).SequenceEqual(path))
      .ToArray();
  }

  private static Trace.Node CreateNodes(List<object> path, Trace.Node node, ApolloTrace.ResolverTrace[] resolvers,
    ref int resolverIndex, ExecutionError[]? executionErrors)
  {
    bool isArray = node.Type.StartsWith("[") && node.Type.TrimEnd('!').EndsWith("]");
    if (isArray)
    {
      if (resolverIndex < resolvers.Length)
      {
        var resolver = resolvers[resolverIndex];
        while (resolver.Path != null && resolver.Path.Count == path.Count + 2 && resolver.Path.Take(path.Count).SequenceEqual(path))
        {
          var index = (int)(resolver.Path[^2]);
          var subPath = path.Concat(new object[] {index}).ToList();

          var previousIndex = resolverIndex;
          node.Childs.Add(CreateNodes(subPath,
            new Trace.Node
            {
              Index = Convert.ToUInt32(index),
              ParentType = node.Type,
              Type = node.Type.TrimStart('[').TrimEnd('!').TrimEnd(']')
            }, resolvers, ref resolverIndex, GetSubErrors(subPath, executionErrors)));

          // Avoid infinite loop if the worst happens and we don't match any items for this index (HOW?!?!?)
          if (resolverIndex == previousIndex)
            resolverIndex++;

          if (resolverIndex >= resolvers.Length)
            break;

          resolver = resolvers[resolverIndex];
        }
      }
    }
    else
    {
      if (resolverIndex < resolvers.Length)
      {
        var resolver = resolvers[resolverIndex];
        while (resolver.Path != null && resolver.Path.Count == path.Count + 1 && resolver.Path.Take(path.Count).SequenceEqual(path))
        {
          var errors = executionErrors?.Where(x => x.Path.SequenceEqual(resolver.Path)).ToArray();
          resolverIndex++;

          node.Childs.Add(CreateNodes(resolver.Path, CreateNodeForResolver(resolver, errors), resolvers,
            ref resolverIndex, GetSubErrors(resolver.Path, executionErrors)));

          if (resolverIndex >= resolvers.Length)
            break;

          resolver = resolvers[resolverIndex];
        }
      }
    }

    return node;
  }
}

So what is all of this doing? Here's an overview:

Retrieve the tracing data added by enabling "Apollo tracing" enrichment of results from the execution result.
Order the resolvers hierarchically (ConfigurationKeyComparer does this beautifully), so that we can consume them in order and avoid expensive full scans of the resolver traces.
Find the root trace (should be the first item).
Collect all root errors from the traces.
Construct a node hierarchy from node paths - this is fairly complicated, but it's easier to see how this works using a sample of data (view one at runtime).
If there's no traces, but there are errors, add those to the root node.
Return a Trace object (from protobuf generated classes) for queuing for send in a batch.

Up Next

In the next article, we'll look at how to generate and send the full report class to Apollo Studio.