Documentation
¶
Overview ¶
Package core holds the LogSense client implementation: option wiring, the single background sender goroutine, and the retry/backoff delivery logic. The top-level logsense package is a thin facade over this package.
Index ¶
- type Client
- func (c *Client) Capture(err error, ctx context.Context, extra ...map[string]any)
- func (c *Client) Dropped() int64
- func (c *Client) Flush()
- func (c *Client) Log(ctx context.Context, level, message string, fields ...map[string]any)
- func (c *Client) Shutdown()
- func (c *Client) StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, *Span)
- type Option
- func WithBatchSize(n int) Option
- func WithContextEnricher(fn func(ctx context.Context) (traceID string, fields map[string]any)) Option
- func WithEndpoint(url string) Option
- func WithEnvironment(env string) Option
- func WithHTTPClient(hc *http.Client) Option
- func WithMaxQueue(n int) Option
- func WithOnError(fn func(error)) Option
- func WithService(name string) Option
- type Span
- type SpanOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the LogSense SDK client. Create one with New().
Its state is split into DTO structs: cfg (user settings), stream (the channels the sender goroutine uses), and stats (runtime counters).
A single background goroutine owns delivery: events flow through the bounded stream.Events channel to one sender, so there are never concurrent in-flight batches and memory can't grow without bound if the endpoint is slow or down.
func (*Client) Capture ¶
Capture enqueues an error for async ingest. Never panics.
The error message is used verbatim as the event Message so repeated occurrences of the same error group together; the stack trace is attached as a structured field rather than embedded in the message.
Note: the stack is captured at the point Capture is called. If you call it from inside a logging hook, the stack reflects the hook, not the error's origin — call Capture at the site where the error is handled for best results.
func (*Client) Dropped ¶
Dropped returns the number of events discarded because the queue was full. A non-zero, growing value means the endpoint can't keep up with your volume.
func (*Client) Flush ¶
func (c *Client) Flush()
Flush sends all currently-buffered events synchronously and waits for the send to complete. Safe to call after Shutdown (returns immediately).
func (*Client) Shutdown ¶
func (c *Client) Shutdown()
Shutdown flushes any buffered events and stops the background goroutine. Idempotent. Always call it (or defer it) before your process exits.
func (*Client) StartSpan ¶
func (c *Client) StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, *Span)
StartSpan begins a span named name. If ctx already carries a span, the new one inherits its trace ID and becomes its child; otherwise a new trace is started. The returned context carries the new span so nested StartSpan calls link up.
Always end the span:
ctx, span := client.StartSpan(ctx, "GET /checkout") defer span.End()
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithBatchSize ¶
WithBatchSize sets how many events accumulate before an early flush. Default 50.
func WithContextEnricher ¶
func WithContextEnricher(fn func(ctx context.Context) (traceID string, fields map[string]any)) Option
WithContextEnricher registers a function that pulls correlation data out of the context.Context passed to Capture/Log — typically an OpenTelemetry trace/span ID. Returning a non-empty traceID sets the event's TraceID; any returned fields are merged into the event's structured data (without overwriting explicit fields). This keeps the SDK dependency-free while still letting logs correlate with traces.
func WithEndpoint ¶
WithEndpoint overrides the default API endpoint.
func WithEnvironment ¶
WithEnvironment sets a default environment (prod/staging/dev).
func WithHTTPClient ¶
WithHTTPClient supplies a custom *http.Client (for tuned pooling, proxies, or tests). By default the SDK uses its own client with a 5s timeout, never the shared http.DefaultClient.
func WithMaxQueue ¶
WithMaxQueue caps the number of buffered events (logs and spans each get their own queue of this size). When a queue is full new events are dropped (drop-newest) and counted; see Dropped. Default 10000.
func WithOnError ¶
WithOnError registers a callback invoked when a batch cannot be delivered (marshal failure, network error, or non-2xx response after retries). Use it to surface delivery problems — a wrong API key or a 5xx-ing endpoint would otherwise lose logs with no signal. The callback must not block.
func WithService ¶
WithService sets a default service name for all captured logs.
type Span ¶
type Span struct {
// contains filtered or unexported fields
}
Span is an in-progress unit of work. Create one with Client.StartSpan, then call End (typically deferred) to record its duration and enqueue it for delivery. A Span is safe to mutate from the goroutine that owns it; End is idempotent.
func (*Span) End ¶
func (s *Span) End()
End records the span's end time and duration and enqueues it for delivery. Idempotent — only the first call takes effect. Safe to call on a nil span.
func (*Span) SetAttributes ¶
SetAttributes merges attributes into the span (last write wins).
func (*Span) SetError ¶
SetError marks the span as failed: status ERROR with err's message, and an "error" attribute. No-op when err is nil.
type SpanOption ¶
type SpanOption func(*Span)
SpanOption configures a Span at creation.
func WithSpanAttributes ¶
func WithSpanAttributes(attrs map[string]any) SpanOption
WithSpanAttributes attaches initial attributes to the span.
func WithSpanKind ¶
func WithSpanKind(kind string) SpanOption
WithSpanKind sets the span kind (server|client|producer|consumer|internal).
Source Files