{"id":50359808,"url":"https://github.com/getsentry/sentry-lua","last_synced_at":"2026-05-30T01:01:37.197Z","repository":{"id":310508573,"uuid":"1040134549","full_name":"getsentry/sentry-lua","owner":"getsentry","description":"Hackweek project: Sentry SDK for Lua","archived":false,"fork":false,"pushed_at":"2025-08-26T02:13:54.000Z","size":1072,"stargazers_count":19,"open_issues_count":8,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T08:37:23.535Z","etag":null,"topics":["hackweek2025","tag-non-production"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/getsentry.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},"funding":{"custom":["https://sentry.io/pricing/","https://sentry.io/"]}},"created_at":"2025-08-18T14:03:59.000Z","updated_at":"2025-12-29T13:45:09.000Z","dependencies_parsed_at":"2025-08-18T16:10:50.418Z","dependency_job_id":"7d3041dd-287d-49dd-9a46-045e17adf934","html_url":"https://github.com/getsentry/sentry-lua","commit_stats":null,"previous_names":["getsentry/sentry-lua"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/getsentry/sentry-lua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-lua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-lua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-lua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-lua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsentry","download_url":"https://codeload.github.com/getsentry/sentry-lua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-lua/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33676191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["hackweek2025","tag-non-production"],"created_at":"2026-05-30T01:01:36.365Z","updated_at":"2026-05-30T01:01:37.175Z","avatar_url":"https://github.com/getsentry.png","language":"Lua","funding_links":["https://sentry.io/pricing/","https://sentry.io/"],"categories":[],"sub_categories":[],"readme":"# Sentry SDK for Lua\n\n\u003e NOTE: This is a hackweek project and not officially supported by Sentry.\n\u003e Not all platforms are yet tested.\n\u003e \n\u003e We accept PRs if you're willing to fix bugs and add features.\n\u003e If there's enough interest, we could invest more into this.\n\n[![Tests](https://github.com/getsentry/sentry-lua/actions/workflows/test.yml/badge.svg)](https://github.com/getsentry/sentry-lua/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/getsentry/sentry-lua/branch/main/graph/badge.svg)](https://codecov.io/gh/getsentry/sentry-lua)\n\nA platform-agnostic Sentry SDK for Lua environments. Written in Teal Language for better type safety and developer experience.\n\nThe goal of this SDK is to be *portable* Lua code, so CI/tests run on Standard Lua, as well as LuaJIT, which can run on [Game Consoles](https://luajit.org/status.html#consoles),\none of [Sentry's latest platform investments](https://blog.sentry.io/playstation-xbox-switch-pc-or-mobile-wherever-youve-got-bugs-to-crush-sentry/).\n\n![Screenshot of this example app](./example-event.png \"Example Lua error with source context, logs and trace connected\")\n\n## Features\n\n- **Platform Agnostic**: Works across Redis, nginx, Roblox, game engines, and standard Lua\n- **Type Safe**: Written in Teal Language with full type definitions\n- **Comprehensive**: Error tracking, breadcrumbs, context management, and scoped operations\n- **Performance Monitoring**: Object-oriented API for transactions and spans with distributed tracing\n- **Distributed Tracing**: Automatic trace propagation across service boundaries via HTTP headers\n- **Structured Logging**: Built-in logging with batching, print hooks, and trace correlation\n- **Extensible**: Pluggable transport system for different environments\n\n## Supported Platforms\n\n- Standard Lua 5.1+ environments\n- Roblox game platform\n- LÖVE 2D game engine\n- Solar2D/Corona SDK\n- Defold game engine\n- Redis (lua scripting)\n- nginx/OpenResty\n\n## Installation\n\n### LuaRocks (macOS/Linux)\n```bash\n# Install from LuaRocks.org - requires Unix-like system for Teal compilation\nluarocks install sentry/sentry\n```\n**Note:** Use `sentry/sentry` (not just `sentry`) as the plain `sentry` package is owned by someone else.\n\n### Direct Download (Windows/Cross-platform)\nFor Windows or systems without make/compiler support:\n1. Download the latest `sentry-lua-sdk-publish.zip` from [GitHub Releases](https://github.com/getsentry/sentry-lua/releases)\n2. Extract the contents\n3. Add the `build/sentry` directory to your Lua `package.path`\n4. No compilation required - contains pre-built Lua files\n\n```lua\n-- Example usage after extracting to project directory\npackage.path = package.path .. \";./build/?.lua;./build/?/init.lua\"\nlocal sentry = require(\"sentry\")\n```\n\n### Development (From Source)\n```bash\n# Clone the repository and build from source\ngit clone https://github.com/getsentry/sentry-lua.git\ncd sentry-lua\nmake install  # Install build dependencies\nmake build    # Compile Teal sources to Lua\nluarocks make --local  # Install locally\n```\n\n### Platform-Specific Instructions\n\n#### Roblox\nImport the module through the Roblox package system or use the pre-built releases.\n\n#### LÖVE 2D\nThe SDK automatically detects the Love2D environment and uses the lua-https module for reliable HTTPS transport. Use the direct download method and copy the SDK files into your Love2D project:\n\n```lua\n-- main.lua\nlocal sentry = require(\"sentry\")\nlocal logger = require(\"sentry.logger\")\n\nfunction love.load()\n    sentry.init({\n        dsn = \"https://your-dsn@sentry.io/project-id\",\n        environment = \"love2d\",\n        release = \"0.0.6\"\n    })\n    \n    -- Optional: Enable logging integration\n    logger.init({\n        enable_logs = true,\n        max_buffer_size = 10,\n        flush_timeout = 5.0\n    })\nend\n\nfunction love.update(dt)\n    -- Flush transport periodically\n    sentry.flush()\nend\n\nfunction love.quit()\n    -- Clean shutdown\n    sentry.close()\nend\n```\n\n**HTTPS Support**: The Love2D example includes a pre-compiled `https.so` binary from [lua-https](https://github.com/love2d/lua-https) for reliable SSL/TLS support. This binary is committed to the repository for convenience. If you need to rebuild it for your platform:\n\n```bash\ncd examples/love2d/lua-https\ncmake -Bbuild -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install\ncmake --build build --target install\n# Copy install/https.so to your Love2D project\n```\n\nSee `examples/love2d/` for a complete interactive demo with error triggering and visual feedback.\n\n## Quick Start\n\n```lua\nlocal sentry = require(\"sentry\")\n\n-- Initialize with your DSN\nsentry.init({\n   dsn = \"https://your-dsn@sentry.io/project-id\",\n   environment = \"production\",\n   release = \"0.0.6\"\n})\n\n-- Capture a message\nsentry.capture_message(\"Hello Sentry!\", \"info\")\n\n-- Capture an exception\nlocal success, err = pcall(function()\n   error(\"Something went wrong!\")\nend)\n\nif not success then\n   sentry.capture_exception({\n      type = \"MyError\",\n      message = err\n   })\nend\n\n-- Flush pending events immediately\nsentry.flush()\n\n-- Clean shutdown\nsentry.close()\n```\n\n## API Reference\n\n- `sentry.init(config)` - Initialize the Sentry client with configuration\n- `sentry.capture_message(message, level)` - Capture a log message  \n- `sentry.capture_exception(exception, level)` - Capture an exception\n- `sentry.set_user(user)` - Set user context\n- `sentry.set_tag(key, value)` - Add a tag for filtering\n- `sentry.set_extra(key, value)` - Add extra debugging information\n- `sentry.add_breadcrumb(breadcrumb)` - Add a breadcrumb for debugging context\n- `sentry.flush()` - Force immediate sending of pending events\n- `sentry.close()` - Clean shutdown of the Sentry client\n- `sentry.with_scope(callback)` - Execute code with isolated scope\n- `sentry.wrap(main_function, error_handler)` - Wrap function with error handling\n\n## Distributed Tracing\n\nThe Sentry Lua SDK supports distributed tracing to improve debuggability across app and service boundaries.\nTraces let you see how telemetry (errors/events, logs, etc) from different processes links together, making it easier to follow execution paths and uncover issues.\nIn addition, through spans, they highlight performance characteristics of your application, helping you detect and resolve bottlenecks.\n\n### Requirements\n\nFor the distributed tracing examples, you'll need additional dependencies:\n\n```bash\nluarocks install pegasus    # HTTP server framework\nluarocks install luasocket  # HTTP client library\n```\n\n### Basic Tracing\n\n```lua\nlocal sentry = require(\"sentry\")\nlocal performance = require(\"sentry.performance\")\n\nsentry.init({\n   dsn = \"https://your-dsn@sentry.io/project-id\"\n})\n\n-- Start a transaction\nlocal transaction = performance.start_transaction(\"user_checkout\", \"http.server\")\n\n-- Add spans for different operations\nlocal validation_span = transaction:start_span(\"validation\", \"Validate cart\")\n-- ... validation logic ...\nvalidation_span:finish(\"ok\")\n\nlocal payment_span = transaction:start_span(\"payment.charge\", \"Process payment\")\n-- ... payment logic ...\npayment_span:finish(\"ok\")\n\n-- Finish the transaction\ntransaction:finish(\"ok\")\n```\n\n### Advanced Tracing Features\n\n#### Nested Spans and Context Management\n\n```lua\nlocal transaction = performance.start_transaction(\"api_request\", \"http.server\")\n\n-- Nested spans automatically maintain parent-child relationships\nlocal db_span = transaction:start_span(\"db.query\", \"Get user data\")\nlocal user_id = get_user_from_db()\ndb_span:finish(\"ok\")\n\n-- Spans can be nested further\nlocal processing_span = transaction:start_span(\"processing\", \"Process user data\")\n\nlocal validation_span = processing_span:start_span(\"validation\", \"Validate permissions\")\nvalidate_user_permissions(user_id)\nvalidation_span:finish(\"ok\")\n\nlocal enrichment_span = processing_span:start_span(\"enrichment\", \"Enrich user data\")\nenrich_user_data(user_id)\nenrichment_span:finish(\"ok\")\n\nprocessing_span:finish(\"ok\")\ntransaction:finish(\"ok\")\n```\n\n#### Adding Context and Tags\n\n```lua\nlocal transaction = performance.start_transaction(\"checkout\", \"business.process\")\n\n-- Add tags and data to transactions\ntransaction:add_tag(\"user_type\", \"premium\")\ntransaction:add_tag(\"payment_method\", \"credit_card\")\ntransaction:add_data(\"cart_items\", 3)\ntransaction:add_data(\"total_amount\", 99.99)\n\nlocal span = transaction:start_span(\"payment.process\", \"Charge credit card\")\n-- Add context to individual spans\nspan:add_tag(\"processor\", \"stripe\")\nspan:add_data(\"amount\", 99.99)\nspan:add_data(\"currency\", \"USD\")\n\n-- Finish with status\nspan:finish(\"ok\")  -- or \"error\", \"cancelled\", etc.\ntransaction:finish(\"ok\")\n```\n\n### Distributed Tracing Examples\n\nThe SDK includes complete examples demonstrating distributed tracing:\n\n- `examples/tracing/client.lua` - HTTP client that propagates trace context\n- `examples/tracing/server.lua` - HTTP server with distributed tracing endpoints\n\nTo see distributed tracing in action:\n\n1. Start the server: `lua examples/tracing/server.lua`\n2. In another terminal, run the client: `lua examples/tracing/client.lua`\n3. Check your Sentry dashboard to see connected traces across both processes\n\nThe examples demonstrate:\n- Object-oriented API with method chaining on transactions and spans\n- Automatic trace context propagation via HTTP headers (`sentry-trace`, `baggage`)\n- Proper parent-child span relationships across service boundaries\n- Error correlation within distributed traces\n- Performance monitoring with detailed timing information\n\n#### Manual Trace Propagation\n\nFor custom HTTP implementations or other transport mechanisms:\n\n```lua\nlocal tracing = require(\"sentry.tracing\")\n\n-- Get trace headers for outgoing requests\nlocal headers = tracing.get_request_headers(\"https://api.example.com\")\n-- headers will contain sentry-trace and baggage headers\n\n-- Continue trace from incoming headers on the receiving side\nlocal incoming_headers = {\n    [\"sentry-trace\"] = \"abc123-def456-1\",\n    [\"baggage\"] = \"user_id=12345,environment=prod\"\n}\ntracing.continue_trace_from_request(incoming_headers)\n\n-- Now start transaction with continued trace context\nlocal transaction = performance.start_transaction(\"api_handler\", \"http.server\")\n-- This transaction will be part of the distributed trace\n```\n\n**Benefits of the new API:**\n- **No global state**: Each transaction and span is explicitly managed\n- **Better control**: Clear ownership of when operations start and finish  \n- **Proper nesting**: Spans automatically inherit from their parent transaction/span\n- **Type safety**: Full Teal type definitions for all methods\n- **Easier debugging**: No hidden global state to track\n\n## Structured Logging\n\nThe Sentry Lua SDK provides comprehensive logging capabilities with automatic batching, trace correlation, and print statement capture.\n\n### Basic Logging\n\n```lua\nlocal sentry = require(\"sentry\")\nlocal logger = require(\"sentry.logger\")\n\nsentry.init({\n   dsn = \"https://your-dsn@sentry.io/project-id\",\n   _experiments = {\n      enable_logs = true,\n      hook_print = true  -- Automatically capture print() calls\n   }\n})\n\n-- Initialize logger\nlogger.init({\n   enable_logs = true,\n   max_buffer_size = 100,\n   flush_timeout = 5.0,\n   hook_print = true\n})\n\n-- Log at different levels\nlogger.trace(\"Fine-grained debugging information\")\nlogger.debug(\"Debugging information\")\nlogger.info(\"General information\")\nlogger.warn(\"Warning message\")\nlogger.error(\"Error occurred\")\nlogger.fatal(\"Critical failure\")\n```\n\n### Structured Logging with Parameters\n\n```lua\n-- Parameterized messages for better searchability\nlocal user_id = \"user_123\"\nlocal order_id = \"order_456\"\n\nlogger.info(\"User %s placed order %s\", {user_id, order_id})\nlogger.error(\"Payment failed for user %s with error %s\", {user_id, \"CARD_DECLINED\"})\n\n-- With additional attributes\nlogger.info(\"Order completed successfully\", {user_id, order_id}, {\n   order_total = 149.99,\n   payment_method = \"credit_card\",\n   shipping_type = \"express\",\n   processing_time = 1.2\n})\n```\n\n### Automatic Print Capture\n\n```lua\n-- These print statements are automatically captured as logs\nprint(\"Application started\")  -- Becomes info-level log\nprint(\"Debug:\", user_id, order_id)  -- Multiple arguments handled\n\n-- No infinite loops - Sentry's own print statements are ignored\n```\n\n### Log Correlation with Traces\n\n```lua\nlocal transaction = performance.start_transaction(\"checkout\", \"business_process\")\n\n-- Logs within transactions are automatically correlated\nlogger.info(\"Starting checkout process\")\n\nlocal span = transaction:start_span(\"validation\", \"Validate cart\")\nlogger.debug(\"Validating cart for user %s\", {user_id})\nspan:finish(\"ok\")\n\nlogger.warn(\"Payment processor slow: %sms\", {2100})\ntransaction:finish(\"ok\")\n\n-- All logs will have trace_id linking them to the transaction\n```\n\n### Advanced Configuration\n\n```lua\nlogger.init({\n   enable_logs = true,\n   max_buffer_size = 50,     -- Batch up to 50 logs\n   flush_timeout = 10.0,     -- Flush every 10 seconds\n   hook_print = true,        -- Capture print statements\n   \n   before_send_log = function(log_record)\n      -- Filter sensitive information\n      if log_record.body:find(\"password\") then\n         return nil  -- Don't send this log\n      end\n      \n      -- Add custom attributes\n      log_record.attributes[\"custom_field\"] = {\n         value = \"custom_value\",\n         type = \"string\"\n      }\n      \n      return log_record\n   end\n})\n```\n\n## Automatic Error Capture\n\nFor automatic capture of unhandled errors, use `sentry.wrap()` to wrap your main application function:\n\n```lua\nlocal sentry = require(\"sentry\")\n\nsentry.init({\n   dsn = \"https://your-dsn@sentry.io/project-id\"\n})\n\nlocal function main()\n   -- Your application logic here\n   local config = nil\n   local db_url = config.database_url  -- This error will be automatically captured\nend\n\n-- Simple automatic error capture\nlocal success, result = sentry.wrap(main)\n\nif not success then\n   print(\"Error occurred but was sent to Sentry:\", result)\nend\n```\n\nYou can also provide a custom error handler:\n\n```lua\nlocal function custom_error_handler(err)\n   print(\"Custom handling:\", err)\n   -- Perform cleanup, logging, etc.\n   return \"Handled gracefully\"\nend\n\nlocal success, result = sentry.wrap(main, custom_error_handler)\n```\n\nThe `sentry.wrap()` approach automatically includes all your Sentry context (user data, tags, breadcrumbs) with captured errors, making it much simpler than manually wrapping every error-prone operation with `pcall`/`xpcall`.\n\nSee `examples/wrap_demo.lua` for a complete demonstration.\n\n## Examples\n\nThere are several [examples in this repository](/examples/).\n\nFor example, the LÖVE framework example app:\n\n![Screenshot of this example app](./examples/love2d/example-app.png \"LÖVE Example App\")\n\n## Development\n\n### Prerequisites\n- Teal Language compiler\n- busted (for testing)\n- Docker (for integration tests)\n\n### Building\n```bash\nmake install     # Install dependencies\nmake build       # Compile Teal to Lua\nmake test        # Run unit tests\nmake docs        # Generate documentation\nmake serve-docs  # Serve docs at http://localhost:8000\nmake lint-soft   # Lint with warnings (permissive)\n```\n\n### Testing\n```bash\n# Unit tests\nmake test\n\n# Docker integration tests\nmake docker-test-redis\nmake docker-test-nginx\n\n# Full test suite\nmake test-all\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fsentry-lua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsentry%2Fsentry-lua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fsentry-lua/lists"}