{"id":22937749,"url":"https://github.com/ktranish/logs","last_synced_at":"2025-04-01T19:30:21.051Z","repository":{"id":263181496,"uuid":"888741624","full_name":"ktranish/logs","owner":"ktranish","description":"A lightweight, developer-friendly log management library built with Elasticsearch for effortless log capturing, querying, and storage.","archived":false,"fork":false,"pushed_at":"2025-01-02T08:41:24.000Z","size":50,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-02T09:39:02.438Z","etag":null,"topics":["elasticsearch","kibana","log-management","logging","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@ktranish/logs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ktranish.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-11-14T23:31:57.000Z","updated_at":"2024-11-18T09:23:01.000Z","dependencies_parsed_at":"2025-01-02T09:34:14.863Z","dependency_job_id":"ec5b104f-f253-42e1-96df-e4022b78d6b9","html_url":"https://github.com/ktranish/logs","commit_stats":null,"previous_names":["ktranish/logs"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktranish%2Flogs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktranish%2Flogs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktranish%2Flogs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktranish%2Flogs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ktranish","download_url":"https://codeload.github.com/ktranish/logs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237645269,"owners_count":19343758,"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":["elasticsearch","kibana","log-management","logging","typescript"],"created_at":"2024-12-14T12:14:13.733Z","updated_at":"2025-02-07T12:28:11.910Z","avatar_url":"https://github.com/ktranish.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Logs\n\n\u003eA lightweight, developer-friendly log management library built with Elasticsearch for effortless log capturing, querying, and storage.\n\n## About\n\n**Logs** is a flexible log management library designed to streamline the process of capturing, storing, and querying logs. Built with Elasticsearch integration, it provides developers with the tools to handle structured logging efficiently, whether in local development or production environments.\n\nWith built-in support for Docker, **Logs** ensures a seamless developer experience by allowing users to spin up a local Elasticsearch instance right out of the box.\n\n## Features\n\n- 🌟 **Unified API**: Simplifies logging, querying, and document management into a single utility.\n- 🚀 **Elasticsearch Integration**: Out-of-the-box support for Elasticsearch with robust client management.\n- 🛠 **Configurable**: Supports custom Elasticsearch setups with local or remote instances.\n- 🌟 **Standalone or Integrated**: Use as a standalone library or integrate with other packages.\n- 📦 **TypeScript Support**: Full TypeScript definitions for better developer experience.\n\n## Prerequisites\n\nBefore using the package, ensure you have an Elasticsearch instance running. You can use a local instance via Docker or a managed Elasticsearch service like AWS OpenSearch or Elastic Cloud.\n\n### Local Elasticsearch Setup with Docker\n\n1. Create a `docker-compose.yml` file:\n\n```yaml\nversion: \"3.8\"\n\nservices:\n  elasticsearch:\n    image: docker.elastic.co/elasticsearch/elasticsearch:8.5.0\n    container_name: elasticsearch\n    environment:\n      - discovery.type=single-node\n      - xpack.security.enabled=false\n    ports:\n      - \"9200:9200\"\n      - \"9300:9300\"\n    volumes:\n      - elastic_data:/usr/share/elasticsearch/data\n\n  kibana:\n    image: docker.elastic.co/kibana/kibana:8.5.0\n    container_name: kibana\n    ports:\n      - \"5601:5601\"\n    environment:\n      ELASTICSEARCH_HOSTS: http://elasticsearch:9200\n\nvolumes:\n  elastic_data:\n```\n\n2. Start Elasticsearch:\n\n```bash\ndocker-compose up -d\n```\n\n3. Verify Elasticsearch is running:\n\n```bash\ncurl http://localhost:9200/_cluster/health\n```\n\n### Installation\n\nInstall Logs via your preferred package manager:\n\n```bash\n# npm\nnpm install @ktranish/logs\n\n# yarn\nyarn add @ktranish/logs\n\n# pnpm\npnpm add @ktranish/logs\n```\n\n## Usage\n\n### 1. Initializing Elasticsearch\n\nUse `setupElasticsearch` to connect to your Elasticsearch instance.\n\n#### Local Elasticsearch\n\n```tsx\nimport { setupElasticsearch } from \"@ktranish/logs\";\n\nasync function initializeLogs() {\n  await setupElasticsearch({\n    url: \"http://localhost:9200\",\n  });\n}\n\ninitializeLogs();\n```\n\n#### Managed Elasticsearch\n\n```tsx\nimport { setupElasticsearch } from \"@ktranish/logs\";\n\nasync function initializeLogs() {\n  await setupElasticsearch({\n    url: \"https://managed-elasticsearch.example.com\",\n    username: \"elastic\",\n    password: \"securepassword\",\n  });\n}\n\ninitializeLogs();\n```\n\n### 2. Logging\n\n```tsx\nimport { Logs } from \"@ktranish/logs\";\n\n// Initialize the utility for your index\nconst logs = new Logs(\"application-logs\");\n\n// Log a message\nawait logs.log(\"info\", \"User logged in\", { userId: 12345 });\n```\n\n### 3. Querying Logs\n\n```tsx\n// Search for logs matching a query\nconst results = await logs.search({\n  query: {\n    match: {\n      message: \"error\",\n    },\n  },\n});\n\nconsole.log(\"Search results:\", results.hits.hits);\n```\n\n### 4. Count Logs\n\n```tsx\nconst count = await logs.count({\n  query: {\n    match: {\n      level: \"info\",\n    },\n  },\n});\n\nconsole.log(`Found ${count} info-level logs.`);\n```\n\n### 5. Document Management\n\n#### Add a Document\n\n```tsx\nawait logs.addDocument({\n  message: \"User signed up\",\n  level: \"info\",\n  metadata: { userId: 67890 },\n  timestamp: new Date().toISOString(),\n});\n```\n\n#### Update a Document\n\n```tsx\nawait logs.updateDocument(\"document-id\", {\n  level: \"warn\",\n});\n```\n\n#### Delete a Document\n\n```tsx\nawait logs.deleteDocument(\"document-id\");\n```\n\n### 6. Bulk Operations\n\n```tsx\nawait logs.bulk([\n  { index: { _id: \"1\" } },\n  { message: \"Bulk log 1\", level: \"info\", timestamp: new Date().toISOString() },\n  { index: { _id: \"2\" } },\n  { message: \"Bulk log 2\", level: \"error\", timestamp: new Date().toISOString() },\n]);\n```\n\n### 7. Index Management\n\n#### Check if Index Exists\n\n```tsx\nconst exists = await logs.indexExists();\nconsole.log(`Index exists: ${exists}`);\n```\n\n#### Create an Index\n\n```tsx\nawait logs.createIndex({\n  number_of_shards: 3,\n  number_of_replicas: 1,\n});\n```\n\n#### Delete an Index\n\n```tsx\nawait logs.deleteIndex();\n```\n\n## Using with Next.js\n\n### Example: Logging API Route\n\n```tsx\n// src/app/api/log/route.ts\nimport { Logs } from \"@ktranish/logs\";\nimport { setupElasticsearch } from \"@ktranish/logs\";\n\n// Ensure Logs is initialized\nawait setupElasticsearch({\n  url: \"http://localhost:9200/\",\n});\n\nexport async function POST(req: Request) {\n  const logs = new Logs(\"application-logs\");\n\n  try {\n    const { level, message, metadata } = await req.json();\n\n    if (!level || !message) {\n      return new Response(\n        JSON.stringify({ error: \"Missing 'level' or 'message'.\" }),\n        { status: 400 }\n      );\n    }\n\n    await logs.log(level, message, metadata || {});\n    return new Response(JSON.stringify({ status: \"Log created.\" }), {\n      status: 200,\n    });\n  } catch (error) {\n    console.error(\"Logging failed:\", error);\n    return new Response(JSON.stringify({ error: \"Logging failed.\" }), {\n      status: 500,\n    });\n  }\n}\n```\n\n## API Reference\n\n### Logs\n\nA unified utility for interacting with Elasticsearch indices.\n\n#### Constructor\n\n```tsx\nconstructor(index: string)\n```\n\n| Parameter | Type     | Description                               |\n| --------- | -------- | ----------------------------------------- |\n| `index`   | `string` | The Elasticsearch index to interact with. |\n\n#### Logging Methods\n\n- `log(level, message, metadata)`\n\n| Parameter    | Type                       | Description                     |\n| ------------ | -------------------------- | ------------------------------- |\n| `level`      | `info, warn, error, debug` | Severity level                  |\n| `message`    | `string`                   | Log message.                    |\n| `metadata`   | `Record\u003cstring, any\u003e`      | Additional metadata (optional). |\n\n#### Querying Methods\n\n- `search(query)`: Executes a search query on the index.\n- `count(query)`: Counts documents matching a query.\n\n#### Document Management\n\n- `addDocument(document)`: Adds a document to the index.\n- `updateDocument(id, partialDoc)`: Updates fields in an existing document.\n- `deleteDocument(id)`: Deletes a document by its ID.\n\n#### Index Management\n\n- `indexExists()`: Checks if the index exists.\n- `createIndex(settings)`: Creates a new index with settings.\n- `deleteIndex()`: Deletes the index.\n\n#### Bulk Operations\n\n- `bulk(operations)`: Executes bulk operations (e.g., add, update, delete).\n\n## Development\n\n### Scripts\n\n- `pnpm build`: Compile the TypeScript source code to JavaScript.\n- `pnpm docker-up`: Start Elasticsearch using Docker Compose.\n- `pnpm docker-down`: Stop Elasticsearch containers and clean up.\n- `pnpm test`: Run unit tests using Jest.\n\n## Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature-name`).\n3. Commit your changes (`git commit -m 'Add new feature'`).\n4. Push to the branch (`git push origin feature-name`).\n5. Open a Pull Request.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktranish%2Flogs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktranish%2Flogs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktranish%2Flogs/lists"}