{"id":15178817,"url":"https://github.com/vedadiyan/lokiclient","last_synced_at":"2025-10-26T17:31:18.632Z","repository":{"id":252034378,"uuid":"839203368","full_name":"Vedadiyan/lokiclient","owner":"Vedadiyan","description":"A Go client for Grafana Loki","archived":false,"fork":false,"pushed_at":"2024-11-04T02:47:44.000Z","size":63,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T21:52:37.118Z","etag":null,"topics":["grafana","logging","loki"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vedadiyan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-07T06:41:26.000Z","updated_at":"2024-11-04T02:47:48.000Z","dependencies_parsed_at":"2024-08-07T10:09:46.805Z","dependency_job_id":"063f7695-4ab2-4933-96c9-55eca36037ae","html_url":"https://github.com/Vedadiyan/lokiclient","commit_stats":{"total_commits":39,"total_committers":2,"mean_commits":19.5,"dds":0.07692307692307687,"last_synced_commit":"6358f93cde3622de48421f07a3668084c5bfc080"},"previous_names":["vedadiyan/loki-client"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vedadiyan%2Flokiclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vedadiyan%2Flokiclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vedadiyan%2Flokiclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vedadiyan%2Flokiclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vedadiyan","download_url":"https://codeload.github.com/Vedadiyan/lokiclient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238375182,"owners_count":19461565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grafana","logging","loki"],"created_at":"2024-09-27T15:23:22.249Z","updated_at":"2025-10-26T17:31:13.340Z","avatar_url":"https://github.com/Vedadiyan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grafana Loki Client for Go\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [Installation](#installation)\n3. [Quick Start](#quick-start)\n4. [Core Concepts](#core-concepts)\n   - [Stream](#stream)\n   - [Entry](#entry)\n5. [Client Configuration](#client-configuration)\n   - [Creating a New Client](#creating-a-new-client)\n   - [Client Options](#client-options)\n6. [Logging Methods](#logging-methods)\n7. [Synchronization](#synchronization)\n8. [Batching and Performance](#batching-and-performance)\n9. [Error Handling and Retries](#error-handling-and-retries)\n10. [Fallback Loggers](#fallback-loggers)\n11. [HTTP Client Customization](#http-client-customization)\n12. [Advanced Usage](#advanced-usage)\n\n## Introduction\n\nThis Go package provides a client for Grafana Loki, a horizontally-scalable, highly-available, multi-tenant log aggregation system. The client allows you to send log entries to a Loki server with various configuration options for performance and reliability.\n\n## Installation\n\nTo install the Loki client, use the following go get command:\n\n```\ngo get github.com/vedadiyan/lokiclient\n```\n\n## Quick Start\n\nHere's a simple example to get you started:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"github.com/vedadiyan/lokiclient\"\n    \"time\"\n)\n\nfunc main() {\n    client := lokiclient.NewClient(\"http://loki:3100\")\n    \n    stream := lokiclient.NewStream(\"myapp\", \"module1\", \"function1\", \"trace123\")\n   \n    client.Info(context.Background(), stream, \"log message\")\n    \n    ctx, cancel := context.WithCancel(context.Background())\n    defer cancel()\n    \n    client.Sync(ctx)\n    \n    // Your application code here\n    time.Sleep(5 * time.Second)\n}\n```\n\n## Core Concepts\n\n### Stream\n\nA `Stream` represents the metadata associated with a log entry. It's implemented as a `map[string]string`.\n\n```go\nstream := lokiclient.NewStream(\"myapp\", \"module1\", \"function1\", \"trace123\")\n```\n\nYou can also create a custom stream:\n\n```go\ncustomStream := lokiclient.NewStreamCustom(map[string]string{\n    \"app\": \"myapp\",\n    \"environment\": \"production\",\n    \"server\": \"server01\",\n})\n```\n\n### Entry\n\nAn `Entry` combines a `Stream` and a `Value`. It's the basic unit of data sent to Loki.\n\n## Client Configuration\n\n### Creating a New Client\n\nCreate a new Loki client by specifying the Loki server address:\n\n```go\nclient := lokiclient.NewClient(\"http://loki:3100\")\n```\n\n### Client Options\n\nYou can customize the client behavior using the following options:\n\n#### WithRetry\n\nConfigure retry behavior:\n\n```go\nlokiclient.WithRetry(3, time.Second)\n```\n\nThis sets a maximum of 3 retries with a 1-second pause between retries.\n\n#### WithBatchSync\n\nEnable batched synchronization:\n\n```go\nlokiclient.WithBatchSync(100, 5*time.Second)\n```\n\nThis batches log entries, sending them when either 100 entries are accumulated or 5 seconds have passed.\n\n#### WithFallback\n\nAdd a fallback logger:\n\n```go\nlokiclient.WithFallback(myFallbackLogger)\n```\n\nThis adds a fallback logger to use if sending to Loki fails.\n\n#### WithLogLevel\n\nAdd log level:\n\n```go\nlokiclient.WithLogLevel(lokiclient.ERROR)\n```\n\n#### WithLogLevel\n\nAdd http timeout:\n\n```go\nlokiclient.WithHttpTimeout(time.Second * 10)\n```\n\n#### WithHttpClient\n\nYou can customize the HTTP client used by the Loki client:\n\n```go\ncustomHttpClient := \u0026http.Client{\n    Timeout: 10 * time.Second,\n}\nlokiclient.WithHttpClient(customHttpClient)\n```\n\n## Logging Methods\n\nThe client provides methods for different log levels:\n\n- `Trace(ctx context.Context, stream Stream, value Value)`\n- `Debug(ctx context.Context, stream Stream, value Value)`\n- `Info(ctx context.Context, stream Stream, value Value)`\n- `Warn(ctx context.Context, stream Stream, value Value)`\n- `Error(ctx context.Context, stream Stream, value Value)`\n\nExample:\n\n```go\nclient.Info(context.Background(), stream, \"log message\")\n```\n\n## Synchronization\n\nStart the synchronization process:\n\n```go\nctx, cancel := context.WithCancel(context.Background())\ndefer cancel()\nclient.Sync(ctx)\n```\n\nThis starts a goroutine that handles sending log entries to Loki.\n\n## Batching and Performance\n\nThe client supports batching of log entries for improved performance. When batching is enabled, entries are grouped by their stream before being sent to Loki.\n\nTo enable batching:\n\n```go\nclient := lokiclient.NewClient(\"http://loki:3100\", client.WithBatchSync(100, 5*time.Second))\n```\n\n## Error Handling and Retries\n\nThe client automatically retries failed requests based on the configured retry settings. If all retries fail, it will attempt to use any configured fallback loggers.\n\n## Fallback Loggers\n\nFallback loggers are used when the client fails to send logs to Loki after all retries. You can add multiple fallback loggers:\n\n```go\nlockiclient.WithFallback(consoleLogger, fileLogger)\n```\n\n## Advanced Usage\n\n### Custom Stream Creation\n\nCreate streams with custom labels:\n\n```go\nstream := lokiclient.NewStreamCustom(map[string]string{\n    \"app\": \"myapp\",\n    \"environment\": \"production\",\n    \"server\": \"server01\",\n})\n```\n\n### Manual Writing of Entries\n\nYou can manually write entries using the `Write` method:\n\n```go\nentries := []*lokiclient.Entry{\n    {\n        Stream: stream,\n        Values: [][]any{\n            {fmt.Sprintf(\"%d\", time.Now().UnixNano()), \"Message 1\"},\n            {fmt.Sprintf(\"%d\", time.Now().UnixNano()), \"Message 2\"},\n        },\n    },\n}\nerr := client.Write(entries)\nif err != nil {\n    // Handle error\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvedadiyan%2Flokiclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvedadiyan%2Flokiclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvedadiyan%2Flokiclient/lists"}