{"id":5296,"library":"libhoney","title":"libhoney Python Library","description":"libhoney is a Python library for sending structured events to Honeycomb, an observability platform for debugging software in production. It is a low-level library designed for direct interaction with Honeycomb's Events API. The library is actively maintained, with a recent major release (2.4.0) in March 2024, and maintains a regular release cadence.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/honeycombio/libhoney-py","tags":["observability","honeycomb","telemetry","structured logging","events"],"install":[{"cmd":"pip install libhoney","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.7 or newer.","package":"python","optional":false}],"imports":[{"symbol":"libhoney","correct":"import libhoney"}],"quickstart":{"code":"import libhoney\nimport os\nimport time\n\n# Initialize libhoney with your API key and dataset name.\n# It's recommended to retrieve these from environment variables.\nlibhoney.init(\n    writekey=os.environ.get('HONEYCOMB_API_KEY', 'YOUR_API_KEY'),\n    dataset=os.environ.get('HONEYCOMB_DATASET', 'my-python-app'),\n    service_name='my-python-app'\n)\n\ntry:\n    # Create a new event\n    ev = libhoney.new_event()\n\n    # Add fields to the event\n    ev.add_field('event_type', 'example_event')\n    ev.add_field('request.method', 'GET')\n    ev.add_field('request.path', '/api/v1/data')\n    ev.add_field('duration_ms', 123.45)\n    ev.add_field('user.id', 'user-123')\n\n    # Send the event asynchronously\n    ev.send()\n    print(\"Event sent successfully (asynchronously).\")\n\n    # For demonstration, wait a bit for asynchronous send\n    time.sleep(0.1)\n\nfinally:\n    # It's crucial to call libhoney.close() on application shutdown\n    # to ensure all buffered events are sent.\n    libhoney.close()\n    print(\"libhoney closed, all events flushed.\")","lang":"python","description":"Initializes the libhoney library, creates a new event, adds various fields, and sends it to Honeycomb. It demonstrates best practices for API key handling via environment variables and proper shutdown procedures to ensure all events are flushed."},"warnings":[{"fix":"Upgrade to Python 3.7+ and libhoney v2.3.0+ for continued support.","message":"Python 2.7 support was dropped in v2.0.0. If you are on an older Python 2.x environment, you must upgrade Python or use an older libhoney version.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Ensure your Python environment is 3.7 or newer.","message":"The minimum supported Python version was raised to 3.5 in v2.0.0, and further to 3.7 in v2.3.0. Versions of Python older than 3.7 are no longer supported.","severity":"breaking","affected_versions":"<2.3.0"},{"fix":"Always call `libhoney.close()` as part of your application's graceful shutdown logic. Consider monitoring the responses queue for delivery confirmation.","message":"Events are sent asynchronously in batches. Not calling `libhoney.close()` upon application shutdown can result in buffered events not being sent to Honeycomb, leading to data loss.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Evaluate OpenTelemetry for new instrumentation. Use libhoney for structured events/logs when OpenTelemetry is not suitable or for existing libhoney integrations.","message":"For new applications requiring tracing, Honeycomb recommends using OpenTelemetry Python SDK instead of libhoney for its standardized, vendor-agnostic, and future-proof approach to telemetry (traces, logs, and metrics).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the type and permissions of your Honeycomb API key in your Honeycomb environment settings. For new datasets, ensure the key has 'Can create datasets' enabled.","message":"Honeycomb API keys have different types and permissions. 'Classic-flavored' ingest keys are now explicitly supported in v2.4.0, but general ingest keys can have permissions like 'Can create datasets'. Ensure your API key has the necessary permissions and is the correct type for your use case.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If response processing is critical, you can set `block_on_response=True` during `libhoney.init()` or ensure you have a separate thread continuously reading from `libhoney.responses()`.","message":"Responses from Honeycomb (e.g., status codes) are placed in an internal queue. If this queue is not actively read from, responses may be dropped if the queue becomes full. By default, sending threads are not blocked by the response queue being full.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `libhoney.new_event()` to create an event and then call `.send()` on the event object.","message":"The `send_now` method was deprecated in favor of `new_event().send()`, which batches events for more efficient transmission.","severity":"deprecated","affected_versions":"<1.6.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}