libhoney Python Library

Warnings

• breaking 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.
  Fix: Upgrade to Python 3.7+ and libhoney v2.3.0+ for continued support.
• breaking 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.
  Fix: Ensure your Python environment is 3.7 or newer.
• gotcha 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.
  Fix: Always call `libhoney.close()` as part of your application's graceful shutdown logic. Consider monitoring the responses queue for delivery confirmation.
• gotcha 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).
  Fix: Evaluate OpenTelemetry for new instrumentation. Use libhoney for structured events/logs when OpenTelemetry is not suitable or for existing libhoney integrations.
• gotcha 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.
  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.
• gotcha 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.
  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()`.
• deprecated The `send_now` method was deprecated in favor of `new_event().send()`, which batches events for more efficient transmission.
  Fix: Use `libhoney.new_event()` to create an event and then call `.send()` on the event object.

Install

• pip install libhoney Install with pip

Imports

• libhoney

  import libhoney

Quickstart

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.

import libhoney
import os
import time

# Initialize libhoney with your API key and dataset name.
# It's recommended to retrieve these from environment variables.
libhoney.init(
    writekey=os.environ.get('HONEYCOMB_API_KEY', 'YOUR_API_KEY'),
    dataset=os.environ.get('HONEYCOMB_DATASET', 'my-python-app'),
    service_name='my-python-app'
)

try:
    # Create a new event
    ev = libhoney.new_event()

    # Add fields to the event
    ev.add_field('event_type', 'example_event')
    ev.add_field('request.method', 'GET')
    ev.add_field('request.path', '/api/v1/data')
    ev.add_field('duration_ms', 123.45)
    ev.add_field('user.id', 'user-123')

    # Send the event asynchronously
    ev.send()
    print("Event sent successfully (asynchronously).")

    # For demonstration, wait a bit for asynchronous send
    time.sleep(0.1)

finally:
    # It's crucial to call libhoney.close() on application shutdown
    # to ensure all buffered events are sent.
    libhoney.close()
    print("libhoney closed, all events flushed.")