Introduction

pinqloq is a logging service.

You only need a pinqloq account and a secret key to get started.

The SDK runs inside your backend and sends your logs to the panel.

Before you start

Two ways to log

Send events from a client app to pinqloq through your own backend.

A client (phone, browser, or POS device) must never hold the secret key. The client sends events to an endpoint you create on your backend. Your backend then uses the pinqloq .NET SDK to forward those events to pinqloq. The secret key stays on your server.

How a client log travels

The app's only job is to send the event to your backend.

The client never calls pinqloq directly. It posts the event and any extra context to an endpoint on your backend. You decide what to include in the payload.

Example request to your backend

curl -X POST https://your-backend.example.com/logs \
  -H "Content-Type: application/json" \
  -d '{ "event": "checkout_completed", "orderId": "A-1042", "screen": "cart" }'

Inject IPinqloqLogger and call Enqueue from anywhere in your backend. You build the PinqloqLogEntry yourself and decide which fields to include. Use LogSourceType.Backend for backend events and LogSourceType.Device to forward events from a client app.

Before you start

What are you logging?

pinqloqLogger.Enqueue(new PinqloqLogEntry
{
    Event            = "order_placed",
    DeviceIdentifier = "u-9821",
    LogLevel         = PinqloqLogLevel.Information,
    LogSourceType    = PinqloqLogSourceType.Backend,
    Metadata         = new()
    {
        ["userId"]   = "u-9821",
        ["tenantId"] = "t-502"
    },
    Detail           = new()
    {
        ["orderId"]      = "A-1042",
        ["totalAmount"]  = "149.99"
    }
},
onFailed: (entry, error) => Console.WriteLine($"Log failed: {error.Reason}"),
onSent:   entry => Console.WriteLine("Log sent"));

pinqloqLogger.Enqueue(new PinqloqLogEntry
{
    Event            = "order_placed",
    DeviceIdentifier = "device-8f3a12",
    LogLevel         = PinqloqLogLevel.Information,
    LogSourceType    = PinqloqLogSourceType.Device,
    CollectionName   = "client_logs",
    Metadata         = new()
    {
        ["battery"]     = "72%",
        ["networkType"] = "wifi"
    },
    Detail           = new()
    {
        ["orderId"]    = "A-1042",
        ["itemCount"]  = "3"
    }
},
onFailed: (entry, error) => Console.WriteLine($"Log failed: {error.Reason}"),
onSent:   entry => Console.WriteLine("Log sent"));

PinqloqLogEntry fields

Which method to call

One line, a fixed template, every request logged.

Call UsePinqloqRequestLogging() once in Program.cs to log every request. The SDK fills in all fields automatically.

Use built-in pinqloq middleware when you want zero per-request code and complete coverage of every HTTP request with no extra effort. It is the right choice for most applications.

Before you start

var app = builder.Build();

app.UsePinqloqRequestLogging();

app.UsePinqloqRequestLogging(options =>
{
    options.ExcludePaths("/health", "/swagger", "/api/client-events");
});

Advanced usage

Use AddMetadata or AddDetail to add custom fields to your logs. Each callback receives the HttpContext and runs once per request. If a callback returns null or throws, that key is skipped. Your keys do not overwrite built-in fields. The only exception is event (the panel title). It defaults to "{method} {path}" and lives in Metadata. To override it, use AddMetadata("event", …).

Use SetDeviceIdentifier to resolve the required DeviceIdentifier per request (for example from a claim, header, or trace id). Use SetAppVersionName to set the version label per request. Both fall back to the matching global option (DeviceIdentifier / AppVersionName) when the callback returns null or empty.

app.UsePinqloqRequestLogging(options =>
{
    // Optional: the middleware already reads the "device-identifier" header. Use SetDeviceIdentifier only to override it.
    options.SetDeviceIdentifier(ctx => ctx.User.FindFirst("sub")?.Value);
    // Optional per-request version label — falls back to the global AppVersionName option
    options.SetAppVersionName(ctx => ctx.Request.Headers["X-App-Version"]);

    options.AddMetadata("userId", ctx => ctx.User.FindFirst("sub")?.Value);
    options.AddMetadata("correlationId", ctx => ctx.Request.Headers["X-Correlation-Id"]);

    options.AddDetail("userAgent", ctx => ctx.Request.Headers.UserAgent);
    // Override the default event title (metadata["event"])
    options.AddMetadata("event", ctx => ctx.Request.Path);
});

What gets logged

Each request becomes one log. The Event field (the log title) is set to "{method} {path}" (e.g. GET /api/orders/42). The level comes from the response status. Request details go into Metadata:

Request and response bodies go into Detail (RequestMethod, ResponseCode, InputJson, OutputJson), truncated at 32 KB. Bodies reach the panel — exclude paths that carry secrets or PII. Request and response headers can also be captured, as RequestHeaders and ResponseHeaders.

The dashboard is at pinqloq.pinqponq.io. Create a project here to get your secret key.

A collection is a named bucket where logs are stored in the panel. You need at least one before you can send logs.

Collections can be edited, disabled, or deleted from the dashboard. A key can write only to collections allowed for its project; logging to another collection returns 403 Forbidden.

After the SDK starts sending logs, use the dashboard panel to read them, manage who can see them, and control active panel sessions.

View logs

Manage panel users

Sessions and devices

Each panel user can have up to 3 active sessions. A session is shown as an active device in the user's Devices panel. If a user reaches the session limit, remove an old device to free a slot before signing in again.

Plan limits

The dashboard is used to create projects, collections, keys, and panel users. The log panel at pinqloq-panel.pinqponq.io is where those users sign in to view logs.

Ask an AI assistant about your logs instead of opening the panel. The MCP server connects Claude, Cursor, or any other Model Context Protocol (MCP) client to your logs.

The MCP server is read-only. It reads your logs through the same panel API the log panel itself uses. It cannot write logs, and it cannot change any project, collection, or user in your dashboard.

What you can ask

Example prompts

Ask in plain language. The assistant picks the tool and the arguments for you.

Before you start

{
  "mcpServers": {
    "pinqloq": {
      "url": "https://pinqloq-mcp.pinqponq.io/mcp",
      "headers": { "secret_key": "<your-mcp-key>" }
    }
  }
}

Add the pinqloq NuGet package, then register the SDK once in Program.cs.

dotnet add package pinqloq

SecretKey is required. Set ApiLogsCollectionName when you use the built-in pinqloq middleware or want a default collection. Logs without a CollectionName fall back to this value. Set DeviceIdentifier as the global fallback for the required per-log DeviceIdentifier field, so both middleware and manual logs ship with one.

builder.Services.AddPinqloq(options =>
{
    options.SecretKey             = builder.Configuration["Pinqloq:SecretKey"]!;
    options.ApiLogsCollectionName = builder.Configuration["Pinqloq:ApiLogsCollectionName"]!;
    options.DeviceIdentifier      = Environment.MachineName;
    options.AppVersionName        = builder.Configuration["Pinqloq:AppVersionName"];
    options.BatchSize             = 200;
    options.FlushInterval         = TimeSpan.FromSeconds(2);
    options.QueueCapacity         = 10000;
    options.HttpTimeout           = TimeSpan.FromSeconds(10);
});

Add a matching Pinqloq section to appsettings.json so these values resolve at runtime (see From appsettings.json below).

Options

From appsettings.json

Bind the options from configuration to keep the secret out of source code:

{
  "Pinqloq": {
    "SecretKey": "lgl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ApiLogsCollectionName": "myapp_api_logs",
    "AppVersionName": "1.0.0"
  }
}

builder.Services.AddPinqloq(options =>
    builder.Configuration.GetSection("Pinqloq").Bind(options));

Delivery callbacks

Enqueue takes two optional callbacks. Pass only the ones you need. Most code only uses onFailed:

With Enqueue (fire and forget, batched in the background):

pinqloqLogger.Enqueue(entry,
    onFailed: (failedEntry, error) =>
        _logger.LogError(error.Exception,
            "Pinqloq log failed: {Reason} ({Status}) - {Message}",
            error.Reason, error.StatusCode, error.Message),
    onSent: sentEntry => { /* optional: metrics, tracing, etc. */ });

onSent runs once the log reaches the server. onFailed runs when the log is dropped or rejected. If the in-memory queue is full, onFailed fires immediately with reason QueueFull and Enqueue returns false.

onFailed gives you a PinqloqLogError:

Production notes

Types & enums

A PinqloqLogEntry uses two enums. In C# you pass the enum value. On the raw HTTP payload, logLevel is a number and logSourceType is a string.

On the raw payload, logLevel is the number 1–5 and logSourceType is the string "Backend" / "Device" (case-insensitive).

Sensitive values — passwords, tokens, card numbers — shouldn't end up in your logs. Add one of two attributes to your code and pinqloq masks them automatically; no other changes needed. This works with MVC controllers, not with minimal API endpoints (app.MapGet/MapPost).

Add [PinqloqRedact] above a single field to hide just that field's value, wherever it shows up — even nested inside another object. Everything else in the request and response is still logged as usual.

public class AuthResponse
{
    [PinqloqRedact]
    public string Token { get; set; } = "";

    public string UserId { get; set; } = "";
}

Add [PinqloqRedactEndpoint] above an entire endpoint — or above the whole controller to cover every endpoint in it — to hide everything it sends and receives: every field, every header. Use it for endpoints that only ever handle sensitive data, like payments or password resets.

[ApiController]
[Route("api/user")]
public class UserController : ControllerBase
{
    [HttpPost("Auth")]
    public AuthResponse Auth([FromBody] AuthRequest request) => ...;

    [PinqloqRedactEndpoint]
    [HttpPost("Payment")]
    public IActionResult Payment([FromBody] PaymentRequest request) => ...;
}

Log for Auth:

{ "token": "*****REDACTED*****", "userId": "64" }

Log for Payment (every value masked, including headers):

{ "cardNumber": "*****REDACTED*****", "amount": "*****REDACTED*****" }

[PinqloqRedact] only works on JSON bodies — if a request or response isn't JSON (form data, plain text), the field you marked is logged as-is, unmasked. [PinqloqRedactEndpoint] doesn't have this gap: a non-JSON body is still replaced with a single masked value, so it's always protected.

Two prompts below cover the two things an AI agent can do for you: add pinqloq logging to your project, or connect an AI assistant to logs you already have. Paste the one you need into Claude Code, Cursor, or any agent.

Integrate the SDK

A machine-readable reference for this prompt is available at documentation.md. The agent reads it, asks you which approach, collection, and fields to use, then applies your choice inside your project.

Integrate the pinqloq .NET SDK into my project. First read the full reference: https://pinqloq.pinqponq.io/documentation.md

If you cannot reach that URL or fail to read the reference, stop immediately, do not guess or write any code, and tell me that you could not load the reference. In that case, I can download the markdown file manually from https://pinqloq.pinqponq.io/documentation.html#ai-prompt and provide it to you directly.

Before anything else, ask me which language I prefer to continue in.

Then inspect my project (Program.cs, appsettings.json, existing middleware, and DI setup) and ask me these questions one step at a time before writing any code:

	1. What do you want to log?
	   - Backend only (HTTP requests, business events, services, background jobs, etc.)
	   - Client only (events coming from a mobile app, web app, or any other device forwarded through your backend)
	   - Both

	2. (If backend was included in question 1) What do you want to log on the backend?
	   - HTTP requests
	   - Other backend events (business events, exceptions, background job results, etc.)
	   - Both

	3. (If HTTP requests was included in question 2) How do you want to log HTTP requests?
	   - Automatically log every HTTP request with built-in pinqloq middleware (note: the middleware wraps the response stream with a buffer to capture the response body, which adds a small memory allocation per request)
	   - Manually log specific HTTP requests using custom logging (inject IPinqloqLogger and call Enqueue from wherever I have the data)

You cannot access the pinqloq dashboard yourself, so also tell me the manual setup I must do there first at https://pinqloq.pinqponq.io: (1) create a project, (2) copy its secret key and store it server-side (user-secrets, an environment variable, or a secret manager; never in client or front-end code), (3) create a collection and copy its name to use as ApiLogsCollectionName or per-entry CollectionName, and (4) open Team Members, use Edit on my admin or owner account, and set a panel password of at least 8 characters (this gives me access to the live log panel to view logs).
After I answer, register the SDK once with AddPinqloq(...) in Program.cs, keep the secret key in config, never log secrets or PII, and finish by summarizing both what you changed in code and the exact dashboard steps I still need to complete.

Connect an AI assistant to your logs

Use this instead if you just want to ask an assistant about logs you already have. No SDK integration needed. See MCP server for what this connects to.

Connect me to the pinqloq MCP server.

{
  "mcpServers": {
    "pinqloq": {
      "url": "https://pinqloq-mcp.pinqponq.io/mcp",
      "headers": { "secret_key": "<my-key>" }
    }
  }
}