Welcome to the experimental Zig SDK for Sentry.
⚠️ Experimental SDK: This SDK is currently experimental and not production-ready. It was developed during a Hackweek project and is intended for testing and feedback purposes.
You need:
- A Sentry account and project
- Zig 0.14.1 or later
Add sentry-zig to your project using the Zig package manager:
# Add the dependency (replace with actual URL when published)
zig fetch --save https://github.com/getsentry/sentry-zig/archive/refs/heads/main.tar.gzThen in your build.zig, add the sentry-zig dependency:
conststd=@import("std");
pubfnbuild(b: *std.Build) void {
consttarget=b.standardTargetOptions(.{});
constoptimize=b.standardOptimizeOption(.{});
// Get the sentry-zig dependencyconstsentry_zig=b.dependency("sentry_zig", .{
.target=target,
.optimize=optimize,
});
constexe=b.addExecutable(.{
.name="my-app",
.root_source_file=b.path("src/main.zig"),
.target=target,
.optimize=optimize,
});
// Add the sentry-zig moduleexe.root_module.addImport("sentry_zig", sentry_zig.module("sentry_zig"));
b.installArtifact(exe);
}Here's a quick configuration example to get Sentry up and running:
conststd=@import("std");
constsentry=@import("sentry_zig");
pubfnmain() !void {
vargpa=std.heap.GeneralPurposeAllocator(.{}){};
defer_=gpa.deinit();
constallocator=gpa.allocator();
// Initialize Sentry - replace with your actual DSNconstdsn="https://your-dsn@o0.ingest.sentry.io/0000000000000000";
constoptions=sentry.SentryOptions{
.environment="production",
.release="1.0.0",
.debug=false,
.sample_rate=1.0,
.send_default_pii=false,
};
varclient=sentry.init(allocator, dsn, options) catch|err| {
std.log.err("Failed to initialize Sentry: {}", .{err});
return;
};
deferclient.deinit();
// Your application code here...std.log.info("Application started with Sentry monitoring", .{});
}With this configuration, Sentry will monitor for exceptions and capture events.
conststd=@import("std");
constsentry=@import("sentry_zig");
// After initializing the client...// Capture messages with different severity levels_=trysentry.captureMessage("Application started successfully", .info);
_=trysentry.captureMessage("Warning: Low memory", .warning);
_=trysentry.captureMessage("Critical error occurred", .@"error");
_=trysentry.captureMessage("System failure - immediate attention required", .fatal);conststd=@import("std");
constsentry=@import("sentry_zig");
constMyError=error{
FileNotFound,
PermissionDenied,
OutOfMemory,
};
fnriskyOperation() !void {
returnMyError.FileNotFound;
}
pubfnmain() !void {
// ... initialize sentry ...// Capture errors with automatic stack traceriskyOperation() catch|err| {
std.debug.print("Caught error: {}\n", .{err});
constevent_id=trysentry.captureError(err);
if (event_id) |id| {
std.debug.print("Error sent to Sentry with ID: {s}\n", .{id.value});
}
};
}For automatic panic reporting, set up the Sentry panic handler:
conststd=@import("std");
constsentry=@import("sentry_zig");
// Set up the panic handler to use Sentry's panic handlerpubconstpanic=std.debug.FullPanic(sentry.panicHandler);
pubfnmain() !void {
// ... initialize sentry ...// Any panic in your application will now be automatically sent to Sentrystd.debug.panic("This will be captured by Sentry!");
}The SentryOptions struct supports various configuration options:
constoptions=sentry.SentryOptions{
.environment="production", // Environment (e.g., "development", "staging", "production")
.release="1.2.3", // Release version
.debug=false, // Enable debug logging
.sample_rate=1.0, // Sample rate (0.0 to 1.0)
.send_default_pii=false, // Whether to send personally identifiable information
};- ✅ Event Capture: Send custom events to Sentry
- ✅ Message Capture: Log messages with different severity levels
- ✅ Error Capture: Automatic error capture with stack traces
- ✅ Panic Handler: Automatic panic reporting
- ✅ Release Tracking: Track releases and environments
- ✅ Debug Mode: Detailed logging for troubleshooting
- ✅ Configurable Sampling: Control event sampling rates
- 🔄 Breadcrumbs: Track user actions and application state
- 🔄 User Context: Attach user information to events
- 🔄 Custom Tags: Add custom tags to events
- 🔄 Performance Monitoring: Track application performance
- 🔄 Integrations: Common Zig library integrations
The repository includes several complete examples in the examples/ directory:
capture_message.zig- Demonstrates message capture with different severity levelscapture_error.zig- Shows error capture with stack tracespanic_handler.zig- Example of automatic panic reporting
Run examples using:
# Build and run the message capture example
zig build capture_message
# Build and run the error capture example
zig build capture_error
# Build and run the panic handler example
zig build panic_handler# Clone the repository
git clone https://github.com/getsentry/sentry-zig.git
cd sentry-zig
# Build the library
zig build
# Run tests
zig build test# Run examples
zig build capture_message
zig build capture_error
zig build panic_handlerThis SDK is experimental. When testing:
- Set up a test Sentry project (don't use production)
- Enable debug mode to see detailed logging
- Check your Sentry dashboard for captured events
- Review the examples for best practices
Current Status: Experimental / Hackweek Project
This SDK was built during a Sentry Hackweek and is not yet ready for production use. We're actively working on:
- Stabilizing the API
- Adding comprehensive tests
- Implementing missing features
- Performance optimizations
- Documentation improvements
We welcome contributions! This is an experimental project and there's lots of room for improvement.
- 🐛 Bug fixes - Report issues or submit fixes
- ✨ Features - Implement missing Sentry features
- 📚 Documentation - Improve docs and examples
- 🧪 Testing - Add tests and improve coverage
- 🔍 Code Review - Review PRs and provide feedback
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
- 📖 Documentation: docs.sentry.io
- 💬 Discord: Sentry Community Discord
- 🐦 Twitter/X: @getsentry
- 📧 Issues: GitHub Issues
This project is licensed under the MIT License. See the LICENSE file for details.
- Sentry Documentation - Complete Sentry documentation
- Zig Language - Learn about the Zig programming language
- Sentry for Other Languages - SDKs for other programming languages
This is an experimental SDK created during a Hackweek project. It is not officially supported by Sentry and should not be used in production environments without thorough testing and evaluation.
Built with ❤️ during Sentry Hackweek