Observability
The EncDotNet.S100 libraries and SoundCharts report logs, traces and metrics through the standard .NET diagnostics APIs. You can see what they're doing in any OpenTelemetry-compatible tool without changing their code.
| Signal | API the libraries use | When nothing subscribes |
|---|---|---|
| Logs | Microsoft.Extensions.Logging.Abstractions ILogger<T> |
NullLogger<T> is used when you don't supply an ILoggerFactory. |
| Traces | System.Diagnostics.ActivitySource |
Inert: StartActivity returns null. |
| Metrics | System.Diagnostics.Metrics.Meter |
Inert until a MeterListener subscribes. |
SoundCharts exports all three over OTLP, so a collector such as the .NET Aspire dashboard, Jaeger, the OpenTelemetry Collector or a Prometheus, Tempo and Loki stack can receive them directly.
Collect telemetry in your own app
The libraries are already instrumented. Subscribe to their sources and meters
in your app's composition root. This example uses the OpenTelemetry and
OpenTelemetry.Exporter.OpenTelemetryProtocol packages:
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("EncDotNet.S100.*")
.AddOtlpExporter()
.Build();
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddMeter("EncDotNet.S100.*")
.AddOtlpExporter()
.Build();
Wildcard names need OpenTelemetry SDK 1.10 or later.
Collect telemetry from SoundCharts
SoundCharts sets up OpenTelemetry in ViewerObservability.AddS100Observability.
The OTLP exporter reads the standard environment variables:
| Variable | Default |
|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
http://localhost:4317 (gRPC) |
OTEL_EXPORTER_OTLP_PROTOCOL |
grpc |
OTEL_SERVICE_NAME |
EncDotNet.S100.Viewer |
OTEL_RESOURCE_ATTRIBUTES |
(none) |
SoundCharts adds the OTLP exporter only when OTEL_EXPORTER_OTLP_ENDPOINT, or
the signal's own OTEL_EXPORTER_OTLP_{LOGS,TRACES,METRICS}_ENDPOINT, is set.
Without one, nothing is exported and nothing retries in the background.
Use the Aspire AppHost
src/EncDotNet.S100.AppHost
is a .NET Aspire host project. It
starts the Aspire dashboard and then starts SoundCharts with the OTLP
endpoint, service name and resource attributes set. It doesn't need Docker.
dotnet run --project src/EncDotNet.S100.AppHost
The console prints a dashboard login URL, such as
http://localhost:15069/login?t=…. Open it to see the app's structured logs,
traces and metrics. Closing either the AppHost console or the app window shuts
down both.
The AppHost project doesn't use central package management.
Use the Aspire dashboard in Docker
To run the dashboard without the AppHost, start it in Docker:
docker run --rm -it -p 18888:18888 -p 4317:4317 \
mcr.microsoft.com/dotnet/aspire-dashboard:latest
Then, in another terminal, start SoundCharts:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
dotnet run --project src/EncDotNet.S100.Viewer
Open http://localhost:18888 to see logs, traces and metrics.
Use Jaeger for traces
docker run --rm -p 16686:16686 -p 4317:4317 \
jaegertracing/all-in-one:latest
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
dotnet run --project src/EncDotNet.S100.Viewer
Open the Jaeger UI at http://localhost:16686.
Write to the console or a file
| Setting | Effect |
|---|---|
ENC_DOTNET_OTEL_CONSOLE=1 |
Also writes logs, traces and metrics to standard output. The AppHost sets this, so they appear in the dashboard's console view. |
ENC_DOTNET_OTEL_FILE=<path> |
Also writes traces and metrics to <path> as newline-delimited JSON, the format the PerfReport tool reads. |
--log-file <PATH> |
Appends structured logs to a file. |
| (always on) | Writes rolling logs, up to 5 files of 1 MB, to a logs folder next to your settings (or under --data-dir). Copies of SoundCharts running side by side share the folder and never delete each other's files while running, so the folder can briefly hold a few more files while several copies run. If a copy crashes, its newest log file is also kept until the next launch has read it for the crash report, even past the 5-file limit: at most 3 such files, and none older than 7 days. --ephemeral runs don't write them. |
-v, --verbose |
Lowers the log level from Information to Debug. |
SoundCharts also keeps its last 1,000 log messages in memory, whatever these
settings are. The Logs tab in the bottom dock shows them, feedback reports
include them as logs.txt, and the get_recent_logs MCP tool returns them.
The tab's Verbose toggle records Debug messages there without changing the
log level the other outputs use. The libraries under the MCP server and HTTP
clients (Microsoft.AspNetCore.*, ModelContextProtocol.* and
System.Net.Http.HttpClient.*) log several messages for every request, so the
buffer keeps only their warnings and errors; otherwise an agent driving the
viewer over MCP would push everything else out of it.
Names
- Each library has one static
Telemetryclass that holds itsActivitySource,Meterand instruments. - Source and meter names match the assembly name, for example
EncDotNet.S100.Datasets.S101orEncDotNet.S100.Renderers.Mapsui. SoundCharts publishes asEncDotNet.S100.Viewer. - Activity, metric and tag names are lowercase and dotted, under
s100.:s100.dataset.open,s100.pipeline.vector.process,s100.hdf5.read.bytes,s100.viewport.zoom. - Tag-key constants are in
EncDotNet.S100.Diagnostics.TelemetryTags, in theEncDotNet.S100.Corepackage.
Traces
A typical SoundCharts command produces this span tree:
s100.viewer.command (kind=Internal, command="dataset.open")
└─ s100.dataset.open
├─ s100.exchangeset.parse
├─ s100.featurecatalogue.parse
├─ s100.hdf5.file.open
├─ s100.hdf5.open{kind=group|dataset} (× N)
└─ s100.hdf5.dataset.read (× N)
└─ s100.pipeline.vector.process [gc.gen0/1/2.delta tags]
├─ s100.pipeline.vector.stage.feature_xml
├─ s100.pipeline.vector.stage.rule_select
├─ s100.pipeline.vector.stage.xslt
│ └─ s100.xslt.transform{rule=…} (× N)
├─ s100.pipeline.vector.stage.lua
│ └─ s100.lua.execute
├─ s100.pipeline.vector.stage.assemble
├─ s100.pipeline.vector.stage.viewing_groups
└─ s100.pipeline.vector.stage.sort
└─ s100.pipeline.coverage.process [gc.gen0/1/2.delta tags]
├─ s100.pipeline.coverage.stage.resolve
└─ s100.pipeline.coverage.stage.read
└─ s100.render.frame
└─ s100.render.coverage.frame
└─ s100.asset.read{kind=file|zip} (× N)
└─ s100.xslt.compile{rule=…} (× N, per catalogue)
- The Lua engine creates a per-rule activity only when a listener subscribes
to it, so a large ENC doesn't flood the trace pipeline. The
s100.lua.rule.invoke.countcounter records rule volume instead. - The
gc.gen0.delta,gc.gen1.deltaandgc.gen2.deltatags on pipeline parent spans are process-wideGC.CollectionCountdifferences. Use them for rough comparisons, not exact attribution.
Tiled renderer spans
When tracing is on, the tiled renderer in EncDotNet.S100.Renderers.Mapsui
adds these spans:
s100.render.tile.job, one per worker job, with child spansdisk_read,rasterizeandpublish. Job tags include the tile keys, priority (visible, predicted or cross-band), queue wait, active worker counts, cache outcome, viewport epoch, stale and published counts, stale-before-raster counts and persistence enqueue results. Raster spans include the candidate paint operation count and output size.s100.render.tile.cache.persist, a root span for each background cache write, with child spanscache.encodeandcache.file_write. Cache writes run on a bounded, low-priority writer after the tile is published. The byte budget is enforced from an in-memory LRU index insidecache.file_write, so no span enumerates the cache directory. The index rescans the directory only on the first write, every ten minutes, or when it notices an external deletion, such as Clear caches in settings.s100.render.tile.composite.slow, for tiled-layer composites that take 50 ms or more. Tags give the layer name, time waiting for the layer-state lock, time spent holding it, cold exposure and visible queue depth. Use it to tell lock contention apart from slow cache or GPU work inside the lock.s100.map.paint.slow, from SoundCharts, for paints that take 50 ms or more. Tags split the paint into summed instrumented style-renderer time and an uninstrumented remainder, and include the paint sequence and draw-call count. The sequence and completion time matchget_render_stats.window.slowestFramefrom the MCP server, so you can match a slow frame to tile jobs, cache writes and runtime traces.
These spans are inert unless an ActivityListener subscribes, so ordinary
runs don't allocate trace records.
Cell load stage spans
Each SoundCharts cell load also splits into stage spans, so you can see where a warm load spends its time:
| Span | Covers |
|---|---|
s100.cell.parse |
Opening and parsing the cell. |
s100.cell.portray |
Portrayal, including the portrayal-cache read. |
s100.portrayal.cache.read |
The disk portrayal-cache read, tagged s100.cache.result (hit or miss). |
s100.cell.scene_build |
Building the Mapsui layers and scene, including the pattern clip. |
s100.cell.pattern_clip |
The pattern clip, tagged s100.cache.result (hit or miss). |
s100.cell.compose |
Composing the map's layer stack. In the viewer, a landing cell's compose runs as a background job outside the load's trace. |
s100.cell.stack_wait |
In the viewer, waiting for a layer stack that includes the landed cell to reach the map: the background compose and the post that applies it. |
To rank slow tile jobs and break down their latency from first visible enqueue
to publish, run PerfReport's tile-report command on a trace file:
dotnet run --project tools/EncDotNet.S100.PerfReport -- \
tile-report path/to/tiles.jsonl --out path/to/tiles.md
Metrics
Each table lists the instruments one meter publishes. The meter name is the package name in the heading.
Pipeline (EncDotNet.S100.Core)
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.pipeline.duration |
histogram | ms |
s100.pipeline.stage, s100.product |
s100.pipeline.stage.duration |
histogram | ms |
s100.pipeline.stage |
s100.pipeline.stage.instructions.count |
histogram | {instructions} |
s100.pipeline.stage |
s100.pipeline.features.in |
histogram | {features} |
s100.product |
s100.pipeline.drawinginstructions.out |
histogram | {instructions} |
s100.product |
s100.coverage.cells |
histogram | {cells} |
s100.product |
s100.xslt.transform.duration |
histogram | ms |
s100.xslt.rule |
s100.xslt.compile.duration |
histogram | ms |
s100.xslt.rule |
s100.lua.execute.duration |
histogram | ms |
— |
s100.lua.features.count |
counter | {features} |
— |
s100.lua.instructions.emitted.count |
histogram | {instructions} |
— |
The same meter also publishes:
s100.lua.feature.instructions.count: drawing instructions the Lua executor emits for one feature type in one pass, tagged withs100.feature.typeands100.product.s100.vector.index.build.duration,s100.vector.index.features.count,s100.vector.index.query.durationands100.vector.index.returned.count: the cost and selectivity of the spatial index over a vector source's features.s100.coverage.pyramid.build.durationands100.coverage.overview.level_selected: the cost of building a coverage overview pyramid, and the pyramid level each coverage read uses (0 is the base grid).
Asset I/O (EncDotNet.S100.Core)
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.asset.read.duration |
histogram | ms |
s100.asset.kind |
s100.asset.bytes.read.count |
counter | By |
s100.asset.kind |
Catalogue resolution (EncDotNet.S100.Datasets.Pipelines)
s100.catalogue.match.count counts catalogue resolutions, tagged with the
product and catalogue versions and the kind of match.
HDF5 (EncDotNet.S100.Hdf5.PureHdf)
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.hdf5.read.bytes |
counter | By |
— |
s100.hdf5.read.duration |
histogram | ms |
— |
Lua rules (EncDotNet.S100.Scripting.LuaCSharp, EncDotNet.S100.Scripting.MoonSharp)
Both engines record the same instruments, each under its own assembly's name.
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.lua.rule.invoke.count |
counter | {calls} |
s100.lua.rule, s100.result |
s100.lua.rule.invoke.duration |
histogram | ms |
s100.lua.rule |
Mapsui renderer (EncDotNet.S100.Renderers.Mapsui)
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.render.frame.duration |
histogram | ms |
— |
s100.render.instructions.processed.count |
counter | {instructions} |
— |
s100.render.styles.applied.count |
counter | {styles} |
— |
s100.symbol.resolve.duration |
histogram | ms |
s100.symbol.result, s100.product |
s100.render.metatile.rasterize.duration |
histogram | ms |
— |
s100.render.metatile.slice.duration |
histogram | ms |
— |
s100.render.metatile.tiles |
histogram | {tile} |
— |
s100.render.metatile.jobs |
counter | {job} |
— |
s100.render.metatile.fallbacks |
counter | {fallback} |
reason |
s100.render.tile.rasterize.duration |
histogram | ms |
— |
s100.render.tile.cold.latency |
histogram | ms |
— |
s100.render.tile.visible.queue.depth |
histogram | {tile} |
— |
s100.render.tile.speculation.deferred |
counter | {worker} |
priority |
s100.render.tile.disk.write_queue.depth |
histogram | {tile} |
— |
s100.render.tile.disk.write_queue.discarded |
counter | {tile} |
reason |
The symbol and pattern cache counters are listed under Cache counters.
- Metatiles. The metatile metrics appear only when
S100_VECTOR_TILE_METATILE=1is set or the Batch adjacent tiles setting is on.rasterize.durationis the time for the whole batched job,slice.durationis the cost of copying it into tiles, andtilesis the number of tiles per batch. The fallbackreasonissparse,disk,scamin,dimensionorscale.scalemeans integer pixel geometry can't preserve the single-tile projection at a fractional device scale.s100.render.tile.rasterize.durationstays comparable with batching on or off: a batched job divides its total time across the tiles it produced. - Speculation.
s100.render.tile.speculation.deferredcounts predicted or cross-band worker admissions rejected while any layer still has visible cold work. A non-zero count means visible-first scheduling is protecting the current viewport. If it keeps growing after the visible queue drains, a layer's active registration is stale. - Disk write queue. Queue overflow and duplicate requests are discarded,
not pushed back onto render workers. The discard
reasoncan also bestale, when a queued tile leaves the viewport before its snapshot, encoding or file commit.
The same meter also publishes:
s100.render.scene.rasterize.duration,s100.render.scene.composite.durationands100.render.tile.composite.duration: off-thread rasterization and UI-thread composite times.s100.render.tile.cold.exposure: visible tiles missing from the cache at each composite.s100.render.tile.prediction.rasterizedands100.render.tile.prediction.hits: speculative tiles, and the ones that later became visible while cached. Their ratio is the prediction hit rate.s100.render.tile.hidden.skippedands100.render.tile.layer.hidden.skipped: tiles and whole layer frames skipped because finer coverage hides them.s100.render.tile.disk.hits,s100.render.tile.disk.writes,s100.render.tile.gpu.uploadsands100.render.tile.gpu.hits: disk cache and GPU texture use.s100.render.tile.faults: render-thread paint faults caught and turned into a dropped frame. It stays at zero in normal operation.s100.layer.getfeatures.duration,s100.layer.getfeatures.visible.count,s100.layer.getfeatures.total.count,s100.layer.getfeatures.calls.count,s100.layer.getfeatures.fpsands100.layer.frame.interval: per-frame feature filtering cost and frame rate for Mapsui memory layers.
Skia renderer (EncDotNet.S100.Renderers.Skia)
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.render.coverage.duration |
histogram | ms |
— |
s100.coverage.cells.processed.count |
counter | {cells} |
— |
SoundCharts (EncDotNet.S100.Viewer)
| Instrument | Type | Unit | Tags |
|---|---|---|---|
s100.viewer.command.duration |
histogram | ms |
s100.viewer.command |
s100.map.paint.duration |
histogram | ms |
— |
s100.map.paint.interval |
histogram | ms |
— |
The meter also publishes s100.map.paint.style.calls and
s100.map.paint.style.duration (style-renderer draw calls and time per paint,
tagged by style, layer, point bucket and feature class), and
s100.viewer.viewinggroup.toggled and s100.viewer.displayplane.toggled
(how often the user changes a viewing-group or display-plane override).
Cache counters
Each cache between the catalogues, dataset processors and renderer has a hit
counter and a miss counter. Each records 1 per event, so the sums give the
hit rate.
| Instrument | Meter | Unit | Tags |
|---|---|---|---|
s100.symbol.cache.hit.count |
EncDotNet.S100.Renderers.Mapsui |
{hits} |
s100.product |
s100.symbol.cache.miss.count |
EncDotNet.S100.Renderers.Mapsui |
{misses} |
s100.product |
s100.pattern.cache.hit.count |
EncDotNet.S100.Renderers.Mapsui |
{hits} |
s100.product |
s100.pattern.cache.miss.count |
EncDotNet.S100.Renderers.Mapsui |
{misses} |
s100.product |
s100.portrayal.cache.hit.count |
EncDotNet.S100.Portrayals |
{hits} |
s100.product, s100.asset.kind |
s100.portrayal.cache.miss.count |
EncDotNet.S100.Portrayals |
{misses} |
s100.product, s100.asset.kind |
s100.lua.source.cache.hit.count |
EncDotNet.S100.Portrayals |
{hits} |
s100.product |
s100.lua.source.cache.miss.count |
EncDotNet.S100.Portrayals |
{misses} |
s100.product |
s100.featurecatalogue.cache.hit.count |
EncDotNet.S100.Features |
{events} |
s100.product |
s100.featurecatalogue.cache.miss.count |
EncDotNet.S100.Features |
{events} |
s100.product |
s100.productis the product specification name:S-101,S-124,S-131and so on.- On the portrayal counters,
s100.asset.kindis one ofxslt,svg,line_style,area_fill,palette,lua_scriptorlua_source. The asset I/O metrics use the same tag name with different values, so tell them apart by instrument name. - The Lua source cache records both its own
s100.lua.source.cache.*counter and ans100.portrayal.cache.*counter withs100.asset.kind=lua_source. Dashboards that group on the portrayal counter still see Lua sources. - Each dataset processor sets
s100.producton the symbol and pattern counters when it creates itsMapsuiDisplayListRenderer.
A PerfReport summarise report shows these counters as rows like:
| Metric | Sum |
| s100.symbol.cache.hit.count[s100.product=S-101] | 4123 |
| s100.symbol.cache.miss.count[s100.product=S-101] | 38 |
| s100.portrayal.cache.hit.count[s100.product=S-101][s100.asset.kind=svg] | 412 |
| s100.lua.source.cache.hit.count[s100.product=S-101] | 24 |
| s100.featurecatalogue.cache.hit.count[s100.product=S-101] | 19 |
In a warm run, the symbol and portrayal hit counts are much larger than the
miss counts, and the feature catalogue hit count is above zero, because every
dataset opened after the first reuses the cached catalogue. Use
PerfReport diff <baseline.jsonl> <candidate.jsonl> to compare two runs.
Test instrumentation
TelemetrySmokeTests.cs
asserts on emitted activities with a plain ActivityListener; it doesn't
need the OpenTelemetry SDK. Use the same pattern when you add instrumentation:
register a listener, call the API, and assert on OperationName and tags.
What's not included
- Log sinks in the libraries. Use the OTLP log exporter, or add any
Microsoft.Extensions.Loggingprovider, such as Serilog, NLog or the console, in your app. - Allocation and GC profiling. The GC count tags give rough comparisons
only. For allocation profiling, use
dotnet-counters,dotnet-traceor EventPipe. - Dashboards. The project doesn't ship Aspire, Grafana or Tempo dashboards. The instrument names and tags above are meant to be read directly.
Performance baselines
The PerfRunner baseline
command runs every scenario and records its telemetry. Committed baselines are
in tools/EncDotNet.S100.PerfRunner/baselines/<git-sha>/, and
baselines/CURRENT holds the SHA of the latest one.
| File | Contents |
|---|---|
SUMMARY.md |
Git SHA, branch, commit subject, UTC time, runtime details (OS, architecture, CPU count, .NET version), and the mean and P95 of each scenario's primary span. It also says whether the run used only synthetic data or the full corpus. |
<scenario>.jsonl |
Raw telemetry in the JSONL schema version 1: span, histogram and counter records from the measured iterations. |
<scenario>.md |
The scenario's minimum, P50, P90, P95, P99, maximum and mean iteration durations. |
Compare a run with a baseline
Use the PerfReport tool.
summarise lists the top spans by total duration and every histogram and
counter. diff compares a baseline and a candidate side by side and marks
regressions and improvements.
dotnet run --project tools/EncDotNet.S100.PerfReport -- summarise \
tools/EncDotNet.S100.PerfRunner/baselines/<sha>/s101-portray-warm.jsonl
dotnet run --project tools/EncDotNet.S100.PerfReport -- diff \
tools/EncDotNet.S100.PerfRunner/baselines/<sha>/s101-portray-warm.jsonl \
path/to/candidate/s101-portray-warm.jsonl
The default scenarios use the small synthetic datasets in tests/datasets/.
They exercise the same code paths as real data, so they show trends between
commits, but their absolute times are much lower than for a real ENC or
bathymetry grid. A single laptop run is noisy; the CI gate below gives more
reliable comparisons.
CI performance gate
The perf.yml
workflow runs on every pull request to main. It doesn't use the committed
baselines:
- It builds PerfRunner from the base branch and from the pull request.
- It runs both in alternating rounds (5 rounds of 4 iterations per side, after 3 warm-up iterations) on the same runner, so both see the same noise.
- It runs PerfReport
gate, which compares medians and fails the check when a scenario regresses by 10% or more and the change is large relative to the run-to-run spread. Spans and metrics with a baseline median under 100 ms aren't gated. - It re-runs any scenarios close to the threshold for 5 more rounds, then gates them again.
- It posts the report as a comment on the pull request.
For the gate's options and evaluation model, see the PerfRunner and PerfReport READMEs.
Update the committed baseline
After you merge a performance improvement, record a new baseline:
dotnet run --project tools/EncDotNet.S100.PerfRunner -- baseline
Review baselines/<new-sha>/SUMMARY.md, write the new SHA to
tools/EncDotNet.S100.PerfRunner/baselines/CURRENT, and commit the new
directory and CURRENT.