{"id":44608297,"url":"https://github.com/saswatamcode/artemis","last_synced_at":"2026-02-14T11:25:59.072Z","repository":{"id":336112328,"uuid":"1147510388","full_name":"saswatamcode/artemis","owner":"saswatamcode","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-03T08:49:49.000Z","size":154,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T10:47:31.485Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/saswatamcode.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-01T21:18:27.000Z","updated_at":"2026-02-02T20:58:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/saswatamcode/artemis","commit_stats":null,"previous_names":["saswatamcode/artemis"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/saswatamcode/artemis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saswatamcode%2Fartemis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saswatamcode%2Fartemis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saswatamcode%2Fartemis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saswatamcode%2Fartemis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saswatamcode","download_url":"https://codeload.github.com/saswatamcode/artemis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saswatamcode%2Fartemis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29443451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T10:51:12.367Z","status":"ssl_error","status_checked_at":"2026-02-14T10:50:52.088Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-02-14T11:25:57.901Z","updated_at":"2026-02-14T11:25:59.066Z","avatar_url":"https://github.com/saswatamcode.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Artemis\n\nAn experimental distributed tracing database built with Apache Arrow and Parquet.\n\n\u003e **⚠️ WARNING: EXPERIMENTAL - NOT PRODUCTION READY**\n\u003e\n\u003e This project is a proof-of-concept and is **NOT** suitable for production use. It lacks production-grade features.\n\u003e This is primarily an experimental project for exploring distributed tracing storage architectures.\n\u003e\n\u003e _Note: Portions of this codebase were developed with AI assistance._\n\n## Features\n\n- **OTLP Ingestion**: Native OpenTelemetry Protocol (OTLP) support via gRPC\n- **Dual Query APIs**: Jaeger-compatible and Tempo-compatible HTTP APIs\n- **Columnar Storage**: Arrow for hot data (L0), Parquet for cold data (L1+)\n- **Leveled Compaction**: Multi-level compaction with automatic block merging\n- **Write-Ahead Log**: Durable writes with checkpointing and crash recovery\n- **Efficient Indexing**: Fast lookups by trace ID, span ID, and tags\n\n## Usage\n\nArtemis usage:\n```\nArtemis is a high-performance trace storage and query backend.\n\nUsage:\n  artemis [flags]\n  artemis [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  version     Print version information\n\nFlags:\n      --api-addr string                      HTTP API (Jaeger) address (default \":16686\")\n      --block-compaction-interval duration   How often to run block compaction (default 5m0s)\n      --blocks-dir string                    Directory for persisted blocks (default \"./data/blocks\")\n      --checkpoint-interval duration         How often to create WAL checkpoints (default 1m0s)\n      --checkpoint-threshold int             Create checkpoint after N segments (default 5)\n      --compact-interval duration            How often to flush pending data to Arrow batches (default 10s)\n      --enable-compaction                    Enable automatic block compaction (default true)\n      --enable-retention                     Enable automatic retention cleanup\n  -h, --help                                 help for artemis\n      --log.format string                    Output format of log messages. One of: [logfmt, json] (default \"logfmt\")\n      --log.level string                     Only log messages with the given severity or above. One of: [debug, info, warn, error] (default \"info\")\n      --max-block-duration duration          Maximum time range per block (default 2h0m0s)\n      --max-block-spans int                  Maximum spans per block (default 1000000)\n      --min-block-age-l0 duration            Minimum age before compacting L0 blocks (default 10m0s)\n      --min-block-age-l1 duration            Minimum age before compacting L1 blocks (default 2h0m0s)\n      --min-blocks-l0 int                    Minimum L0 blocks to trigger compaction (default 2)\n      --min-blocks-l1 int                    Minimum L1 blocks to trigger compaction (default 2)\n      --otlp-addr string                     OTLP gRPC receiver address (default \":4317\")\n      --retention-period duration            Delete blocks older than this (0 = no retention)\n      --tempo-addr string                    Tempo API address (default \":3200\")\n      --wal-dir string                       Directory for WAL segments (default \"./data/wal\")\n      --wal-segment-size int                 WAL segment size in bytes (default 128MB) (default 134217728)\n\nUse \"artemis [command] --help\" for more information about a command.\n```\n\nartemistool usage\n```\nartemistool is a command-line interface for querying an Artemis trace server via its various APIs.\n\nUsage:\n  artemistool [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  jaeger      Query Artemis using Jaeger API\n  sql         Query Artemis using SQL API\n  tempo       Query Artemis using Tempo API\n\nFlags:\n  -h, --help               help for artemistool\n      --jaeger-port int    Jaeger API port (default 16686)\n      --query-url string   Artemis server query endpoint URL (default \"http://localhost\")\n      --sql-port int       SQL API port (default 5433)\n      --tempo-port int     Tempo API port (default 3200)\n\nUse \"artemistool [command] --help\" for more information about a command.\n```\n\n## Quick Start\n\n### Standard Build (without SQL support)\n\n```bash\n# Build\nmake build\n\n# Run server\n./bin/artemis\n\n# Or with custom configuration\n./bin/artemis \\\n  --wal-dir=./data/wal \\\n  --blocks-dir=./data/blocks \\\n  --otlp-addr=:4317 \\\n  --jaeger-addr=:16686 \\\n  --tempo-addr=:3200\n```\n\n### DuckDB Build (with SQL query support)\n\n```bash\n# Build with DuckDB support (requires CGO)\nmake build-duckdb\n\n# Run server\n./bin/artemis-duckdb\n\n# The SQL API will be available on port 5433 by default\n./bin/artemis-duckdb --sqlapi-addr=:5433\n```\n\n### Build artemistool CLI\n\n```bash\n# Build the query tool\nmake build-tool\n\n# Query using Jaeger API\n./bin/artemistool jaeger search --service my-service --limit 10\n\n# Query using SQL (requires DuckDB build)\n./bin/artemistool sql --query \"SELECT service_name, COUNT(*) as count FROM spans GROUP BY service_name\"\n```\n\n## Architecture\n\nArtemis uses a tiered storage architecture:\n\n1. **WAL**: All writes are first written to a write-ahead log for durability\n2. **Head Block** (L0): In-memory Arrow columnar storage with indexes\n3. **Persisted Blocks** (L0): Arrow IPC files on disk\n4. **Compacted Blocks** (L1+): Parquet files with optimized compression\n\n### Compaction Levels\n\n- **L0**: Arrow IPC format (fast writes, good for queries)\n- **L1**: Parquet format (compressed, optimized for cold storage)\n- **L2**: Larger Parquet blocks (long-term retention)\n\nBlocks are automatically compacted as they age, similar to LSM-tree databases.\n\n## APIs\n\n### OTLP Receiver\n```bash\n# Send traces via OTLP gRPC\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317\n```\n\n### Use Telemetrygen\n```bash\ntelemetrygen traces --otlp-endpoint localhost:4317 --otlp-insecure --traces 10 --service \"my-test-service\" --child-spans 5\n```\n\n### Jaeger API\n```bash\n# Search traces\ncurl \"http://localhost:16686/api/traces?service=my-service\"\n\n# Get trace by ID\ncurl \"http://localhost:16686/api/traces/{traceID}\"\n\n# List services\ncurl \"http://localhost:16686/api/services\"\n```\n\n### Tempo API\n```bash\n# Search with TraceQL\ncurl \"http://localhost:3200/api/search?q={service.name=my-service}\"\n\n# Get trace by ID (OTLP format)\ncurl \"http://localhost:3200/api/traces/{traceID}\"\n\n# List tags\ncurl \"http://localhost:3200/api/v2/search/tags\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaswatamcode%2Fartemis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaswatamcode%2Fartemis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaswatamcode%2Fartemis/lists"}