Heka Sandbox Interface
This document describes the 1.0 release of the Heka sandbox API built on the Generic Sandbox Interface. The 1.0 release is a refined implementation of its predecessor which was developed in Heka. The goal is to decouple it from Go and make it easily embeddable in any language. The Go version of Heka has been deprecated and replaced by Hindsight.
2. Sandbox API Changes from the Go Heka Sandbox
There are a few intentional changes between tho original Heka sandbox and this version.
2.1.1. Input Sandbox
inject_messageaccepts a numeric or string checkpoint as the second argument
process_messagereceives the checkpoint value as the first argument (if it was provided by
2.1.2. Output Sandbox
process_messagereceives a sequence_id as the first argument (if it was provided by
update_checkpoint). Extended return codes have been added to support skipping, retrying, batching, and asynchronous output.
2.1.3. Analysis/Output Sandbox
nilfor optional header fields if they don't exist instead of an empty string or zero
- added a
framedparameter to retrieve the raw message with stream framing
- added a
sizeparameter to retrieve size of the raw message without having to copy it down
timer_eventhas a second parameter
shutdownthat is set to true when the sandbox is exiting.
2.2.1. Input Sandbox
2.2.2. Output Sandbox
- update_checkpoint was added for batch and asynchronous processing.
- create_message_matcher function was added.
write_messageAPI was removed; messages are immutable and this API broke that rule.
read_next_fieldAPI was removed; instead the raw message should be decoded and the Lua table iterated.
read_configAPI in unchanged but now has access to the entire sandbox configuration.