Skip to content
Back to search

LatticeLog

Typed, local-first structured logging for .NET: an open binary log format, indexed queries and an MCP server for agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lreyesm1999--latticelog/badge.svg)](/listings/lreyesm1999--latticelog)

HTML

<a href="/listings/lreyesm1999--latticelog"><img src="/api/listings/lreyesm1999--latticelog/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

You need the [.NET 10 SDK](https://dotnet.microsoft.com/download) (exact version in [`global.json`](global.json)). Packages are not on NuGet yet, so you build from source. About five minutes on a typical machine:

git clone https://github.com/lreyesm1999/LatticeLog.git
cd LatticeLog
dotnet build LatticeLog.sln -c Release

# 1. write ~8,000 events from a simulated order service with an injected incident
dotnet run -c Release --no-build --project examples/dotnet-console -- demo-store 2000

# 2. investigate it (alias the CLI to keep commands short)
alias latticelog="dotnet run -c Release --no-build --project src/LatticeLog.Cli --"   # PowerShell: see the tutorial
latticelog errors demo-store --top 3
latticelog query  demo-store --where "level >= ERROR" --limit 3 --explain
latticelog trace  demo-store --trace-id <id printed by step 1> --format markdown

The [tutorial](docs/guides/getting-started.md) walks through the same incident step by step, then connects your coding agent. To install the CLI once as a single executable (no .NET, no administrator rights):

- **Windows, with a setup wizard:** download `latticelog-win-x64.msi` from the [releases](https://github.com/lreyesm1999/LatticeLog/releases) and run it. You pick the background service, PATH and which AI tools to connect; it appears in *Settings → Apps* for uninstalling. Releases after 0.1.0-alpha.7 include it. - **Or one line:** it downloads the newest release (Windows x64, Linux x64), checks it against `SHA256SUMS` and runs `latticelog setup`:

irm https://raw.githubusercontent.com/lreyesm1999/LatticeLog/main/scripts/install.ps1 | iex   # Windows
curl -fsSL https://raw.githubusercontent.com/lreyesm1999/LatticeLog/main/scripts/install.sh | sh   # Linux

See [Install](docs/guides/install.md) for options, updates and uninstalling.

Use it in your app

<ItemGroup>
  <ProjectReference Include="path/to/LatticeLog/src/LatticeLog.Core/LatticeLog.Core.csproj" />
  <ProjectReference Include="path/to/LatticeLog/src/LatticeLog.Generator/LatticeLog.Generator.csproj"
                    OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
</ItemGroup>
using var logger = LatticeLogger.CreateLocal("./logs", o => o.Resource.Add(new("service.name", "orders-api")));
logger.Info("Hello, LatticeLog");

Already on `ILogger`? Keep your code and add one line: `builder.Logging.AddLatticeLog(logger)`. The [ASP.NET Core example](examples/aspnetcore) shows both side by side, with the request's trace id on every record.

| Guide | | |---|---| | [Getting started](docs/guides/getting-started.md) | The incident above, step by step, then your own app | | [ASP.NET Core and `ILogger`](docs/guides/aspnetcore.md) | Minimal API, `[LoggerMessage]` and `[LatticeEvent]` side by side | | [MCP: Claude Code, Cursor, Claude Desktop, VS Code](docs/guides/mcp.md) | One command per client, logs found by service name | | [Investigating an incident with an agent](docs/guides/investigate-with-an-agent.md) | Which tools an agent calls, and what it gets back | | [Migrating from text or JSON logs](docs/guides/migrating-from-text-logs.md) | Keep your files; convert them on request, losslessly where possible | | [Python](sdks/python) · [PHP](sdks/php) | Local folders (Python) and server shipping (Python, PHP) | | [Troubleshooting](docs/guides/troubleshooting.md) | Common errors and what they mean |

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 256 lines · 2 findings marked
  1. <div align="center">
  2. <img src="docs/assets/latticelog-hero.png" alt="LatticeLog: typed, local-first logs in an open binary format" width="100%">
  3. <h1>LatticeLog</h1>
  4. <p><strong>Typed, local-first logs for .NET, stored in an open binary format you can query by index<br>
  5. and hand to people, scripts or coding agents (over MCP) as evidence that points back to every record.</strong></p>
  6. [![CI](https://github.com/lreyesm1999/LatticeLog/actions/workflows/ci.yml/badge.svg)](https://github.com/lreyesm1999/LatticeLog/actions/workflows/ci.yml)
  7. [![Release](https://img.shields.io/github/v/release/lreyesm1999/LatticeLog?include_prereleases&sort=semver&label=release)](https://github.com/lreyesm1999/LatticeLog/releases)
  8. [![.NET 10](https://img.shields.io/badge/.NET-10-512BD4?logo=dotnet&logoColor=white)](global.json)
  9. [![Status: alpha](https://img.shields.io/badge/status-alpha-A855F7)](#project-status)
  10. [![License: MIT](https://img.shields.io/github/license/lreyesm1999/LatticeLog)](LICENSE)
  11. <p>
  12. <a href="#quick-start">Quick start</a> ·
  13. <a href="docs/guides/getting-started.md">Tutorial</a> ·
  14. <a href="docs/guides/mcp.md">MCP setup</a> ·
  15. <a href="examples">Examples</a> ·
  16. <a href="docs/benchmarks.md">Benchmarks</a> ·
  17. <a href="docs/README.md">Docs</a>
  18. </p>
  19. </div>
  20. ---
  21. ## What it looks like
  22. **The problem.** An order service fails intermittently. The logs are there, but finding *which* failures are the same
  23. failure, and handing that to a teammate or a coding agent, means grepping text and pasting fragments.
  24. **The implementation.** Events are declared once; a source generator writes the logging method at compile time, and
  25. the attribute types (`long`, `int`, `string`…) are kept in storage:
  26. ```csharp
  27. [LatticeEvent(Id = 2102, Name = "order.failed", Level = Severity.Error, Message = "Order {orderId} failed: {reason}")]
  28. public static partial void OrderFailed(ILatticeLogger logger, long orderId, string reason, Exception? error);
  29. ```
  30. **The result.** One command groups the failures deterministically and states what it covered: no sampling, nothing silently truncated. This is real
  31. output from [`examples/dotnet-console`](examples/dotnet-console) (8,037 records, one injected incident), checked on every
  32. CI run by [`scripts/check-examples.sh`](scripts/check-examples.sh):
  33. ```text
  34. $ latticelog errors demo-store --format markdown # excerpt; ids shortened with …
  35. | coverage | value |
  36. |---|---|
  37. | matched_events | 16 |
  38. | returned_events | 2 |
  39. | truncated | False |
  40. | partial_results | False |
  41. | sampling | none |
  42. | exhaustive | yes |
  43. ## Error groups (deterministic fingerprints, not root causes)
  44. - `4971c8d6ee1067be` ×8 ERROR `order.failed` exception=`System.TimeoutException`, first llog://c17423fc…/e/196
  45. - `a85a07c80de55c35` ×8 ERROR `inventory.stock.timeout`, first llog://c17423fc…/e/195
  46. $ latticelog stats demo-store --by event # excerpt
  47. order.received 2000
  48. order.failed 8
  49. -- total 8037 (from footer indexes, no block decoded)
  50. ```
  51. Every `llog://` reference resolves to the original record (`latticelog event demo-store <ref>`). The same tools are
  52. available to Claude Code, Cursor, Claude Desktop or VS Code as an [MCP server](docs/guides/mcp.md) that finds logs
  53. **by service name**. LatticeLog runs no AI itself; it structures, filters and retrieves, and marks log text as untrusted
  54. data.
  55. <p align="center">
  56. <img src="docs/assets/screenshots/console-search.png" alt="LatticeLog web console: a day of events with an incident's errors highlighted in red" width="88%"><br>
  57. <sub>The local web console (<code>llog ui</code>) on <a href="docs/assets/screenshots/README.md">synthetic demo data</a>: a day of events, the incident's errors in red.</sub>
  58. </p>
  59. ---
  60. ## Quick start
  61. You need the [.NET 10 SDK](https://dotnet.microsoft.com/download) (exact version in [`global.json`](global.json)).
  62. Packages are not on NuGet yet, so you build from source. About five minutes on a typical machine:
  63. ```bash
  64. git clone https://github.com/lreyesm1999/LatticeLog.git
  65. cd LatticeLog
  66. dotnet build LatticeLog.sln -c Release
  67. # 1. write ~8,000 events from a simulated order service with an injected incident
  68. dotnet run -c Release --no-build --project examples/dotnet-console -- demo-store 2000
  69. # 2. investigate it (alias the CLI to keep commands short)
  70. alias latticelog="dotnet run -c Release --no-build --project src/LatticeLog.Cli --" # PowerShell: see the tutorial
  71. latticelog errors demo-store --top 3
  72. latticelog query demo-store --where "level >= ERROR" --limit 3 --explain
  73. latticelog trace demo-store --trace-id <id printed by step 1> --format markdown
  74. ```
  75. The [tutorial](docs/guides/getting-started.md) walks through the same incident step by step, then connects your
  76. coding agent. To install the CLI once as a single executable (no .NET, no administrator rights):
  77. - **Windows, with a setup wizard:** download `latticelog-win-x64.msi` from the
  78. [releases](https://github.com/lreyesm1999/LatticeLog/releases) and run it. You pick the background service, PATH
  79. and which AI tools to connect; it appears in *Settings → Apps* for uninstalling. Releases after 0.1.0-alpha.7
  80. include it.
  81. - **Or one line:** it downloads the newest release (Windows x64, Linux x64), checks it against `SHA256SUMS` and runs
  82. `latticelog setup`:
  83. ```powershell
  84. irm https://raw.githubusercontent.com/lreyesm1999/LatticeLog/main/scripts/install.ps1 | iex # Windows
  85. ```
  86. ```bash
  87. curl -fsSL https://raw.githubusercontent.com/lreyesm1999/LatticeLog/main/scripts/install.sh | sh # Linux
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 115 on GitHub
  88. ```
  89. See [Install](docs/guides/install.md) for options, updates and uninstalling.
  90. ### Use it in your app
  91. ```xml
  92. <ItemGroup>
  93. <ProjectReference Include="path/to/LatticeLog/src/LatticeLog.Core/LatticeLog.Core.csproj" />
  94. <ProjectReference Include="path/to/LatticeLog/src/LatticeLog.Generator/LatticeLog.Generator.csproj"
  95. OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  96. </ItemGroup>
  97. ```
  98. ```csharp
  99. using var logger = LatticeLogger.CreateLocal("./logs", o => o.Resource.Add(new("service.name", "orders-api")));
  100. logger.Info("Hello, LatticeLog");
  101. ```
  102. Already on `ILogger`? Keep your code and add one line: `builder.Logging.AddLatticeLog(logger)`. The
  103. [ASP.NET Core example](examples/aspnetcore) shows both side by side, with the request's trace id on every record.
  104. | Guide | |
  105. |---|---|
  106. | [Getting started](docs/guides/getting-started.md) | The incident above, step by step, then your own app |
  107. | [ASP.NET Core and `ILogger`](docs/guides/aspnetcore.md) | Minimal API, `[LoggerMessage]` and `[LatticeEvent]` side by side |
  108. | [MCP: Claude Code, Cursor, Claude Desktop, VS Code](docs/guides/mcp.md) | One command per client, logs found by service name |
  109. | [Investigating an incident with an agent](docs/guides/investigate-with-an-agent.md) | Which tools an agent calls, and what it gets back |
  110. | [Migrating from text or JSON logs](docs/guides/migrating-from-text-logs.md) | Keep your files; convert them on request, losslessly where possible |
  111. | [Python](sdks/python) · [PHP](sdks/php) | Local folders (Python) and server shipping (Python, PHP) |
  112. | [Troubleshooting](docs/guides/troubleshooting.md) | Common errors and what they mean |
  113. ---
  114. ## Why LatticeLog?
  115. | If you need… | LatticeLog gives you | Evidence |
  116. |---|---|---|
  117. | Logging that stays off the hot path | Source-generated typed events: **56 ns, 5 B** per enabled event, **1.1 ns, 0 B** when the level is off | [hot path benchmark](reports/benchmarks-hotpath.md) (null sink, one machine) |
  118. | To find the slice you need without decompressing everything | Time, severity, event and service indexes skip blocks; window queries **20–40×** faster than a full scan | [baseline §3](reports/baseline-v1.md#3-selective-queries-ms-median-of-3-segments--readtotal) |
  119. | Smaller logs than compressed text, for typed events | **−25 %** vs. the same content as CSV + zstd-3 on 14 public Loghub-2.0 datasets (but **+17 %** vs. zstd-19) | [Loghub-2.0 report](reports/loghub2-v1.md) |
  120. | Answers you can trust | Every response states its coverage (truncated? partial? sampled?) and links each item to its source record | [evidence protocol](specs/evidence-protocol.md) |
  121. | Your coding agent to read logs safely | Read-only MCP server, sources by service name, log text marked as untrusted | [MCP guide](docs/guides/mcp.md) |
  122. | No lock-in | Documented format, an independent Python reader that verifies golden files in CI, lossless export to JSONL or OTLP/JSON | [format spec](specs/llog-format-v0.md) · [`tools/pyllog`](tools/pyllog) |
  123. | No infrastructure to start | Files in a folder; an optional per-user service and an optional single-node server | [install](docs/guides/install.md) · [server](docs/deploy/single-node.md) |
  124. Where it does **not** win: storing raw, unstructured text is **+83 %** larger than zstd-3 (it keeps the exact bytes
  125. and makes them queryable, not smaller), and zstd-19 beats it on size everywhere. Both are in the reports.
  126. ## How it compares
  127. Different tools solve different layers. LatticeLog is a library **and** a storage/query engine, so it overlaps with
  128. several of them partly and replaces none of them in general.
  129. | | LatticeLog | Serilog / NLog | Seq | OpenTelemetry .NET | Grafana Loki |
  130. |---|---|---|---|---|---|
  131. | Category | Logging library + local store + query engine | Logging libraries | Log server with UI | Telemetry SDK and protocol | Log aggregation backend |
  132. | Structured, typed attributes | Yes, types kept on disk | Structured properties; storage depends on the sink | Structured events (JSON) | Typed attributes on the wire (OTLP) | Labels indexed; line content as text |
  133. | Compile-time generated log methods | `[LatticeEvent]` generator | Not built in (MEL's `[LoggerMessage]` works with both) | n/a | n/a | n/a |
  134. | Storage and query included | Yes, local files | No (sinks write elsewhere) | Yes, server | No (exports to a backend) | Yes, server + object storage |
  135. | Runs with no server | Yes | Yes | No | Yes (needs a backend to store) | No |
  136. | Open on-disk format, independent reader | Yes | Depends on the sink (text and JSON files are open) | Server-internal storage | n/a (OTLP is an open wire format) | Server-internal storage |
  137. | Access for coding agents (MCP) | Built in, read-only | Not built in | Community MCP servers (not from Datalust) | Not built in | Through Grafana's MCP server |
  138. | Maturity | **Alpha**, one maintainer, no cluster | Mature, widely used | Mature commercial product | Stable, CNCF project | Mature, horizontally scalable |
  139. LatticeLog already exports to OTLP/JSON and imports OTLP, so it can sit next to an OpenTelemetry pipeline rather than
  140. replace it. A longer, sourced comparison is in [docs/comparison.md](docs/comparison.md).
  141. ---
  142. ## Benchmarks
  143. All numbers come from **one machine** (Intel i9-14900KF, Windows 11, .NET 10.0.15, local SSD) and the reports say so.
  144. That machine is unstable under all-core load, so concurrency runs were pinned to 4 CPUs. They are not a sizing guide.
  145. | What | Result | Method | Reproduce |
  146. |---|---|---|---|
  147. | Enabled typed event, producer side | 55.6 ns, 5 B allocated | BenchmarkDotNet, null sink, 1 thread | [report](reports/benchmarks-hotpath.md) |
  148. | Disabled event | 1.12 ns, 0 B | same | same |
  149. | Typed events vs CSV+zstd-3 (Loghub-2.0) | −25 % total (−5 % to −58 %) | first 200k lines of 14 datasets | [report](reports/loghub2-v1.md) |
  150. | `.llog` vs JSONL+zstd-3 (synthetic) | smaller on 7 of 8 workloads (−1.4 % to −23.4 %) | 100k records × 8 workloads | [report](reports/baseline-v1.md) |
  151. | Server ingest, binary body | ~1.15 M records/s | 4 producers, loopback | [report](reports/ingest-v1.md) |
  152. | Log call latency at a fixed rate | p50 0.1–0.3 µs, p99 ≤ 1.5 µs; **intermittent stalls of up to seconds** traced to that machine's nearly full SSD | real store, 10k–500k events/s, coordinated-omission-aware | [report](reports/latency-v1.md) |
  153. Methodology, datasets, versions, raw CSVs and known limitations: **[docs/benchmarks.md](docs/benchmarks.md)**.
  154. [`scripts/reproduce.sh`](scripts/reproduce.sh) reruns the tests, the baseline and the latency benchmark.
  155. ---
  156. ## Architecture
  157. ```mermaid
  158. flowchart LR
  159. subgraph app["Your process"]
  160. A["Typed events<br/><sub>[LatticeEvent] · ILogger bridge</sub>"] --> Q["Bounded ring<br/><sub>producer does no I/O</sub>"]
  161. end
  162. Q --> S[(".llog segments<br/><sub>blocks · catalog · CRC · footer index</sub>")]
  163. PY["Python SDK, local mode<br/><sub>latticelog.jsonl files</sub>"] -->|indexed by name| SVC
  164. T["Old text / JSON logs"] -->|migrate, originals untouched| S
  165. S --> CLI["CLI<br/><sub>query · errors · trace · verify</sub>"]
  166. S --> SVC["Per-user service<br/><sub>sources by name · web console</sub>"]
  167. SVC --> MCP["MCP server<br/><sub>read-only, for coding agents</sub>"]
  168. S -->|Forwarder · idempotent| SRV["latticelog-server<br/><sub>namespaces · tokens · HTTP API</sub>"]
  169. SRV -.->|async| R["Replica"]
  170. PH["Python / PHP SDKs<br/><sub>server mode, durable spool</sub>"] -->|HTTP ingest| SRV
  171. ```
  172. - **Local first.** The application never waits on the network to log. With a server configured, the local store is a
  173. durable outbox.
  174. - **Honest acknowledgements.** `Fast`, `Balanced` or `Durable` (fsync); `FlushAsync` returns the level actually reached.
  175. - **Exactly once at the server.** Every record carries `(producer, sequence)`, so retries are deduplicated.
  176. Details: [features](docs/features.md) · [format spec](specs/llog-format-v0.md) · [architecture decisions](docs/decisions).
  177. ---
  178. ## Project status
  179. **Alpha** (latest pre-release on [Releases](https://github.com/lreyesm1999/LatticeLog/releases)). 232 automated tests,
  180. including real-process crash tests and end-to-end TLS, run in CI on Windows x64, Linux x64, Linux ARM64 and macOS ARM64.
  181. Not production-hardened: the per-phase truth, including what did **not** pass, is in [`ROADMAP.md`](ROADMAP.md).
  182. | Implemented | Experimental | Known limitations | On the [roadmap](ROADMAP.md) |
  183. |---|---|---|---|
  184. | .NET logger, generator, `ILogger` bridge | Lattice-C context encoding (opt-in) | No NuGet / PyPI / Packagist packages | Published packages, stable release (later) |
  185. | `.llog` 0.3 format, recovery, compaction, retention, backup | Async replication with manual failover | No encryption at rest, no external security review | Encryption at rest, external pentest (next) |
  186. | CLI (also Native AOT), MCP server, per-user service | Web console (no browser E2E tests yet) | Benchmarks from one unstable machine | Measurements on stable hardware and Linux (next) |
  187. | Python (local + server) and PHP (server) SDKs | Migration of text/JSON logs | No cluster or object storage | Cluster, object-storage tiers (later) |
  188. | Single-node server: namespaces, tokens, audit, metrics | | Prebuilt executables for Windows x64 and Linux x64 only | Fuller console with user testing |
  189. Changes: [`CHANGELOG.md`](CHANGELOG.md).
  190. ## Contributing
  191. Issues and pull requests are welcome; [`CONTRIBUTING.md`](CONTRIBUTING.md) explains the local setup, the tests and
  192. where to start. Questions go to [`SUPPORT.md`](SUPPORT.md), vulnerabilities to [`SECURITY.md`](SECURITY.md) (privately).
  193. Participation follows the [Code of Conduct](CODE_OF_CONDUCT.md).
  194. ## License
  195. [MIT](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.