Working with Markers¶

Markers annotate your data with events like deployments, configuration changes, or other significant occurrences. They appear as vertical lines on your graphs.

Basic Marker Operations¶

List Markers¶

async def list_markers(client: HoneycombClient, dataset: str) -> list[Marker]:
    """List all markers in a dataset.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug to list markers from

    Returns:
        List of markers
    """
    markers = await client.markers.list_async(dataset)
    for marker in markers:
        print(f"{marker.type}: {marker.message}")
        if marker.url:
            print(f"  URL: {marker.url}")
    return markers

Update a Marker¶

async def update_marker(client: HoneycombClient, dataset: str, marker_id: str) -> Marker:
    """Update a marker's message.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the marker
        marker_id: ID of the marker to update

    Returns:
        The updated marker
    """
    # For markers, you typically need the start_time from the original
    # In practice, you'd retrieve this or keep it from creation
    marker = await client.markers.update_async(
        dataset,
        marker_id,
        MarkerCreate(
            message="Updated: Backend deploy v2.5.0 - success",
            type="deploy",
            start_time=int(time.time()),  # Note: should use original start_time
        ),
    )
    return marker

Delete a Marker¶

async def delete_marker(client: HoneycombClient, dataset: str, marker_id: str) -> None:
    """Delete a marker.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug containing the marker
        marker_id: ID of the marker to delete
    """
    await client.markers.delete_async(dataset, marker_id)

Creating Markers with MarkerBuilder¶

MarkerBuilder provides a fluent interface for creating markers with convenient helpers for time configuration and common patterns.

async def create_marker_with_builder(client: HoneycombClient, dataset: str) -> str:
    """Create a marker using MarkerBuilder.

    This example shows a marker for a past incident that started 3 hours ago
    and lasted for 2 hours, with a link to the incident report.
    """
    import time

    # Calculate timestamp 3 hours ago
    three_hours_ago = int(time.time()) - (3 * 60 * 60)
    two_hours_duration = 2 * 60 * 60

    marker = (
        MarkerBuilder("Production outage - Database connection timeout")
        .type("incident")
        .start_time(three_hours_ago)
        .end_time(three_hours_ago + two_hours_duration)
        .url("https://status.example.com/incidents/2024-001")
        .build()
    )

    created = await client.markers.create_async(dataset, marker)
    return created.id

MarkerBuilder Reference¶

Basic Configuration¶

Method	Description
`.type(marker_type)`	Set marker type (required) - groups similar markers
`.url(url)`	Set target URL (optional) - link to PR, build, incident

Time Configuration¶

Method	Description
`.start_time(timestamp)`	Set start time as Unix timestamp
`.end_time(timestamp)`	Set end time as Unix timestamp (for duration markers)
`.duration_minutes(minutes)`	Set duration from now in minutes
`.duration_hours(hours)`	Set duration from now in hours

Static Methods¶

Method	Description
`MarkerBuilder.setting(type, color)`	Create marker setting (color configuration)

Marker Types¶

Common marker type conventions:

deploy - Deployments and releases
maintenance - Planned maintenance windows
incident - Incidents and outages
config-change - Configuration changes
feature-flag - Feature flag toggles

Creating Markers Manually¶

For simple cases or when you need fine-grained control:

async def create_deploy_marker(client: HoneycombClient, dataset: str) -> str:
    """Create a deployment marker.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug to create marker in

    Returns:
        The created marker ID
    """
    marker = await client.markers.create_async(
        dataset,
        MarkerCreate(
            message="Backend deploy v2.5.0",
            type="deploy",
            start_time=int(time.time()),
        ),
    )
    return marker.id


_with_url
async def create_marker_with_url(client: HoneycombClient, dataset: str) -> str:
    """Create a marker with a link to the PR.

    Args:
        client: Authenticated HoneycombClient
        dataset: Dataset slug to create marker in

    Returns:
        The created marker ID
    """
    marker = await client.markers.create_async(
        dataset,
        MarkerCreate(
            message="Hotfix: Fix memory leak",
            type="deploy",
            url="https://github.com/myorg/myrepo/pull/1234",
            start_time=int(time.time()),
        ),
    )
    return marker.id

Additional Options¶

Markers support several optional fields:

url: Link to PR, build info, or runbook
end_time: For events with duration (e.g., rollouts, maintenance)
dataset: Use "__all__" to create environment-wide markers visible across all datasets

Marker Settings¶

Customize marker colors by type using the marker settings API. All CRUD operations are available:

list_settings_async() / list_settings() - List all marker settings
get_setting_async() / get_setting() - Get a specific setting by ID
create_setting_async() / create_setting() - Create a new marker type with color
update_setting_async() / update_setting() - Update an existing setting
delete_setting_async() / delete_setting() - Delete a setting

Sync Usage¶

All marker operations have sync equivalents:

with HoneycombClient(api_key="...", sync=True) as client:
    # List markers
    markers = client.markers.list("my-dataset")

    # Create marker
    marker = client.markers.create(
        "my-dataset",
        MarkerCreate(message="Deploy v1.0", type="deploy", start_time=int(time.time()))
    )

    # Update marker
    updated = client.markers.update("my-dataset", marker_id, MarkerCreate(...))

    # Delete marker
    client.markers.delete("my-dataset", marker_id)

    # Marker settings
    settings = client.markers.list_settings("my-dataset")