Datalens.Client 1.1.0

Datalens.Client

Client package for applications publishing logs and events to a Datalens Controller. Intended for external consumer apps; the Controller itself does not consume this package.

Installation

dotnet add package Datalens.Client

Targets net8.0 and net10.0.

Registration

Each subsystem is registered explicitly. Register only what you use.

using Microsoft.Extensions.DependencyInjection;

services.AddDatalensLogs(configuration);
services.AddDatalensEvents(configuration);
services.AddDatalensInvoke(configuration);

After AddDatalensLogs, the standard ILogger<T> continues to work unchanged. After AddDatalensEvents, inject IDatalensEvents to publish events. After AddDatalensInvoke, inject IDatalensInvoke to call flow endpoints.

Add* never throws at registration: a misconfigured subsystem logs a single line to stderr, so a typo in your appsettings.json will not crash your application at startup.

Logs and events are best-effort — a misconfigured subsystem stays silently disabled and dropped data is only counted. Invoke is different: it returns a result, so a misconfigured or disabled invoke subsystem registers a stub whose calls throw InvalidOperationException. A request/response call must never silently no-op.

All self-diagnostics from this package (overflow, flush failures, dropped publishes, shipper lifecycle) write to stderr with a [Datalens.Client.Logs] or [Datalens.Client.Events] prefix. They are deliberately routed through Console.Error rather than the host's ILoggerFactory to avoid recursion into the package's own log buffer and to remove a class of DI cycles between the package and the host's logger setup. Azure App Service log streams, Docker compose, systemd, and Kubernetes all capture stderr by default.

Configuration

{
  "DatalensClient": {
    "Endpoint": "https://your-datalens-host",
    "Logs": {
      "Enabled": true,
      "LogKey": "your-log-key",
      "LogLevel": {
        "Default": "Information",
        "Microsoft.EntityFrameworkCore": "Warning"
      },
      "Buffer": {
        "Capacity": 5000,
        "FlushIntervalMs": 5000
      }
    },
    "Events": {
      "Enabled": true,
      "FlowKey": "your-flow-key",
      "Buffer": {
        "Capacity": 50000,
        "FlushIntervalMs": 30000,
        "BatchSize": 100,
        "HttpTimeoutMs": 5000
      }
    },
    "Invoke": {
      "Enabled": true,
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "CustomerSlug": "your-customer-slug",
      "TimeoutSeconds": 100
    }
  }
}

Endpoint and LogKey are supplied by your Datalens administrator. All buffer durations are integer milliseconds.

Invoke.ClientId / Invoke.ClientSecret are the client-credentials pair for your API client; CustomerSlug is your customer's public slug. The client exchanges the credentials for a one-hour bearer token, caches it, and refreshes once automatically on a 401.

FlowKey under Events is a config default. Each IDatalensEvents.PublishLegacyAsync overload accepts an optional per-call flowKey that overrides the config default when provided. If neither the per-call value nor the config default is set, the publish is dropped (with a counter increment and a self-diagnostic) — it does not throw.

Invoke

IDatalensInvoke calls a flow endpoint and returns its result. There are two request shapes.

Vanilla — post bare JSON, read it back typed or raw:

public sealed record Quote(string Symbol, decimal Price);

Quote? quote = await invoke.InvokeAsync<Quote>("price-lookup", new { symbol = "ACME" });

JsonNode? raw = await invoke.InvokeAsync("price-lookup", new { symbol = "ACME" });

Structured — send named collections (JSON, native-typed tabular, and documents) and read named collections back:

DatalensRequest request = DatalensRequest.Create()
    .AddJson("meta", new { source = "nightly" })
    .AddTabular("orders", orders)
    .AddDocument("invoice", pdfBytes, "invoice.pdf", "application/pdf");

DatalensResponse response = await invoke.InvokeAsync("ingest-orders", request);

int? executionId = response.ExecutionId;
IReadOnlyList<Order> back = response.Tabular<Order>("orders");
MyResult? result = response.Json<MyResult>("result");

DatalensDocument receipt = response.Document("receipt");
await using Stream bytes = await receipt.OpenAsync();

Calls throw on failure (unlike the best-effort logs/events sinks):

• DatalensInvokeException — a wire failure: non-2xx response (after one automatic 401 refresh+retry), transport fault, timeout, or unparseable body. Carries StatusCode, the server's ServerError, and ExecutionId when present.
• InvalidOperationException — the subsystem is disabled/misconfigured, or a DatalensResponse accessor was misused (unknown collection name or wrong kind).
• ArgumentException — a bad call argument caught before the network (empty endpoint, empty/duplicate document key, total document upload over 30 MB).

License

Proprietary. See the bundled LICENSE file.