quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Developer’s guide

11. Observe your application

There are two useful views of telemetry. Application Insights and Log Analytics are Azure-compatible resources used by your application and its Microsoft SDKs. Platform diagnostics and Grafana help you operate Quinzee itself. They have separate stores: sending an event to Application Insights does not automatically copy it into Grafana's Tempo/Loki backends.

Step 1: understand the resources

Chapter 5 created a Log Analytics workspace and a workspace-backed Application Insights component. outputs.json contains workspaceId, insightsConnectionString and insightsResourceId.

Use the workspace's customer ID for Logs Query, not its ARM resource ID. Use the returned component connection string so that ingestion targets Quinzee. The template sets DisableLocalAuth: true; the exporter therefore needs the same TokenCredential used elsewhere. It requests a monitoring-audience token.

Step 2: emit a request, log and metric

Replace Program.cs with this complete example. It uses the official Azure.Monitor.OpenTelemetry.Exporter library and Azure.Monitor.Query.Logs, already restored by chapter 3.

using Azure.Monitor.OpenTelemetry.Exporter;
using Azure.Monitor.Query.Logs;
using Microsoft.Extensions.Logging;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using System.Diagnostics;
using System.Diagnostics.Metrics;

var book = BookContext.Load();
var outputs = book.Outputs();
Environment.SetEnvironmentVariable("APPLICATIONINSIGHTS_STATSBEAT_DISABLED", "true");
void Configure(AzureMonitorExporterOptions options)
{
    options.ConnectionString = outputs["insightsConnectionString"];
    options.Credential = book.Credential;
    options.DisableOfflineStorage = true;
    options.TracesPerSecond = null;
    options.SamplingRatio = 1;
    options.Retry.MaxRetries = 1;
    options.Retry.NetworkTimeout = TimeSpan.FromSeconds(5);
}
using var traces = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("quinzee.book"))
    .AddSource("Quinzee.Book")
    .AddAzureMonitorTraceExporter(Configure).Build();
using var metrics = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("quinzee.book"))
    .AddMeter("Quinzee.Book").AddAzureMonitorMetricExporter(Configure).Build();
using var source = new ActivitySource("Quinzee.Book");
using var meter = new Meter("Quinzee.Book");
string traceId;
using (var request = source.StartActivity("book.request", ActivityKind.Server)
    ?? throw new InvalidOperationException("Trace listener is missing"))
{
    traceId = request.TraceId.ToHexString();
    request.SetTag("http.request.method", "GET");
    request.SetTag("http.response.status_code", 200);
    request.SetStatus(ActivityStatusCode.Ok);
    var exporterOptions = new AzureMonitorExporterOptions();
    Configure(exporterOptions);
    using var logs = LoggerFactory.Create(builder => builder.SetMinimumLevel(LogLevel.Information)
        .AddOpenTelemetry(options =>
        {
            options.IncludeFormattedMessage = true;
            options.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("quinzee.book"));
            options.AddProcessor(new SimpleLogRecordExportProcessor(
                new AzureMonitorLogExporter(exporterOptions)));
        }));
    logs.CreateLogger("Book").LogInformation("Book request completed");
}
meter.CreateCounter<long>("book_documents_total").Add(1);
if (!traces.ForceFlush(10000) || !metrics.ForceFlush(10000))
    throw new InvalidOperationException("Telemetry flush timed out");
Console.WriteLine($"Trace ID: {traceId}");

var query = new LogsQueryClient(book.Credential);
async Task<long> WaitForCountAsync(string kql)
{
    using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(30));
    while (true)
    {
        var result = await query.QueryWorkspaceAsync(outputs["workspaceId"], kql,
            new LogsQueryTimeRange(TimeSpan.FromHours(1)),
            cancellationToken: timeout.Token);
        var count = result.Value.Table.Rows[0].GetInt64(0)
            ?? throw new InvalidOperationException("Query did not return a count");
        if (count > 0) return count;
        await Task.Delay(250, timeout.Token);
    }
}
foreach (var table in new[] { "AppRequests", "AppTraces" })
{
    var count = await WaitForCountAsync(
        $"{table} | where OperationId == '{traceId}' | count");
    Console.WriteLine($"{table}: {count}");
}
var metricCount = await WaitForCountAsync(
    "AppMetrics | where Name == 'book_documents_total' | count");
Console.WriteLine($"Metric records: {metricCount}");

Run dotnet run --no-restore. Expect a trace ID and a positive count for each signal. An ActivityKind.Server activity becomes an AppRequests record; client activities represent dependencies. The log shares the activity's operation ID. The explicit flush drains the providers; the query then waits up to 30 seconds for a visible record instead of assuming immediate visibility. A timeout is a failed verification: check ingestion, credentials and the workspace ID. Keep providers alive throughout the lifetime of a long-running application. The synchronous log processor here is for the small demonstration, not a high-throughput logging design.

Sampling must be 100 percent for this local ingestion subset. Set TracesPerSecond = null as well as SamplingRatio = 1: the exporter's default rate limit otherwise takes precedence over the ratio. Statsbeat is disabled for the local example, and failed exports are not saved to an offline cache. Avoid putting passwords, signed URLs, SQL parameters or document content in tags or log messages. Arbitrary application messages are not automatically sanitized just because the destination is a local monitoring workspace.

The exporter batches supported application envelopes and sends them to the component's ingestion endpoint. The query client reads workspace rows through a separate API and audience. Treat a successful export and a successful query as separate checks, and use only the query stages demonstrated below.

Step 3: query useful records

In QHQ Monitoring → Observability → Workspace logs, enter the customer ID from workspaceId, then run one query at a time, for example:

AppRequests | order by TimeGenerated desc | take 50
AppRequests | where Success == false | project Name, ResultCode, DurationMs
AppTraces | where TimeGenerated >= ago(1h) | project TimeGenerated, Message
AppDependencies | where OperationId == 'your-32-character-trace-id' | take 100
AppMetrics | where Name == 'book_documents_total' | count

The tables are AppRequests, AppDependencies, AppTraces, AppExceptions, AppEvents and AppMetrics. Supported stages are where comparisons, project, one-column order by, take/limit, count and summarize count(). Unsupported joins, render operations and other KQL return errors. Queries return at most 1,000 rows; narrow or aggregate a larger result. QHQ displays up to 100 of the returned rows and tells you that limit.

ARM Metrics also exposes request/dependency count, failed and duration metrics on the component. Use requests/count, requests/failed, requests/duration and the corresponding dependencies/… names, with Count, Total, Average, Minimum or Maximum as appropriate. Duration is milliseconds. Custom AppMetrics names are queried through Logs Query rather than that ARM endpoint.

Step 4: diagnose the local platform

For the environment started with make application-observability-up:

  1. Sign into https://localhost:13001, user admin, using .local/observability/grafana-password and its public CA.
  2. Open Quinzee observability for request rates, handler latency/errors, transport throughput, worker activity, sampled queue depth and engine health.
  3. In Explore, select Tempo and search a trace ID from the browser workflow. Select Loki for correlated cloud, application and engine logs.
  4. In QHQ's Health and Requests tabs, refresh diagnostics or filter recent requests by trace ID. This uses authenticated administration APIs.

The browser workflow already exports to this platform stack. The standalone example above exports only to its Application Insights component. To send your own application's traces to Tempo as well, configure an OTLP exporter and its trusted HTTPS collector endpoint separately. The host endpoint is normally https://localhost:14318; in another container, localhost means that container, not Quinzee. Join the collector's network and configure its DNS/name and CA before using its internal endpoint. Do not substitute an Application Insights connection string for an OTLP URL.

/health reports process liveness. /ready reports that identity and Resource Manager are loaded; a stopped SQL server does not make the whole control plane unready. Engine heartbeat/state and worker/queue diagnostics provide the additional evidence. Handler latency excludes transfer time; transport metrics include parsed HTTP exchange/body transfer time. A queue sampling truncation flag means the displayed depth is partial.

QHQ's Observability page with Health, Requests and Workspace logs tabs

QHQ separates platform health, recent requests and workspace log queries. The capture shows a local environment with external OTLP export disabled.

Step 5: understand retention

Workspaces retain 30–730 days by configuration, but also have a hard cap of 4,096 accepted rows per workspace, so a busy local workspace can evict older rows much sooner. Batch ingestion is capped at 1 MiB/256 envelopes, with 8 KiB normalized rows. Queries and ingested state survive cloud restart.

The optional tools keep logs/traces for 24 hours; Prometheus also targets 512 MB retention. Backend WALs and compaction need additional disk space. Stopping the tools preserves their data in .local/observability/data.

Alerts, diagnostic settings, workbooks, profiling, live metrics, DCR/DCE collection, gzip ingestion, sampled envelopes and full KQL are not supported. A local workspace and Grafana dashboard are separate facilities, not a complete Azure Monitor service replica.