We need a synchronous Capture method

[alexreidy]

Our use case is sending backend-processed Kafka messages into PostHog, such as bot-filtered events and revenue indicators. Our event shipping service using this library stopped shipping, silently, but the code passing these important events into the Capture method had no idea anything was wrong and continued as if everything was reaching PostHog when it was actually being thrown away. The message handler that calls the fire-and-forget Capture() has no simple way to determine whether there is an error preventing the asynchronous POSTs to PostHog.

I appreciate the effort that has gone into this dotnet library but I feel strongly that the current Capture() does not meet common needs.

IMO, any problem preventing intended behavior should cause the next Capture() calls to throw an exception, to mitigate loss. Client/user code should be responsible for catching any exceptions and handling as desired. In our case, this would mean logging the error and retrying until success (e.g., the PostHog API starts giving 200s again) or manual intervention. Others may pass the events to a persistent queue until PostHog recovers. The client/user cannot reliably ship events into PostHog unless it is acutely aware of the success/failure of shipping each individual event.

To get around this somewhat, I have followed every single Capture() call with a call to FlushAsync(), hoping exceptions will bubble up. This stopgap has stabilized event shipping in the face of occasional errors, but it's an imperfect solution, especially when sharing the IPostHogClient across multiple distinct event types and handlers, where irrelevant exceptions can be thrown despite the local message having actually been successfully shipped - triggering a retry and duplicate send.

Ideally, we would have a CaptureAsync() which accepts a single event or a batch, directly POSTs to PostHog, and bubbles up any exceptions that occur in the process. This could be an alternative to the fire-and-forget version of Capture. The only time I think anyone would want to use Capture as it exists today is if the events are not important, don't need to be verifiably delivered to PostHog, and can be lost without consequence. Frankly, it should be renamed CaptureOnlyIfEverythingIsWorkingPerfectlyAndWeWillNotTellYouIfItIsBroken(). If it were changed to throw an exception once issues have been detected, with a means of accessing the events that failed to ship, or a general means of inspecting which events were successfully written to PostHog (acks), then it may be useful for low-latency logging scenarios where complete event delivery is still important. For those scenarios, though, I would instead synchronously write the event to Kafka or the like, and trust that eventually it will be verifiably shipped to PostHog by another service that uses a synchronous CaptureAsync()/POST wrapper.

Thank you

[haacked]

Thanks for the suggestion! My hesitation with adding a CaptureAsync method is folks are likely to use it because "It's Async so it must be the correct way" and 99% of folks should be using Capture. We could consider adding something like CaptureInefficientlyAsync or something like that to make it clear, but I want to propose another idea.

It seems there are two key issues:

1. Capture should almost never fail.
2. Failures are silent.

We've done a lot of work to make capture more robust. But there's always going to be failures (network down, etc). So lets add an event handler for batching errors so you can do something like:

Basic error logging

var options = new PostHogOptions
{
    ProjectApiKey = "...",
    OnBatchError = error =>
    {
        _logger.LogError(error.Exception,
            "Failed to send {Count} events to PostHog at {Time}",
            error.EventCount,
            error.Timestamp);
    }
};

Retry with dead letter queue:

var options = new PostHogOptions
{
    ProjectApiKey = "...",
    CollectFailedEvents = true,
    OnBatchError = error =>
    {
        // Send to dead letter queue for retry
        await _deadLetterQueue.EnqueueAsync(error.FailedEvents);
    }
};

Would this satisfy your concerns?