From cebe224bcdc9e796ea6518b5407f035c31cfd7ca Mon Sep 17 00:00:00 2001 From: Alex Holovach Date: Thu, 9 Oct 2025 23:44:56 -0500 Subject: [PATCH] update --- packages/otel-autumn/README.md | 115 ++++++++++++++------------------- 1 file changed, 49 insertions(+), 66 deletions(-) diff --git a/packages/otel-autumn/README.md b/packages/otel-autumn/README.md index 45e4767..858b417 100644 --- a/packages/otel-autumn/README.md +++ b/packages/otel-autumn/README.md @@ -26,7 +26,7 @@ import { instrumentAutumn } from "@kubiks/otel-autumn"; const autumn = instrumentAutumn( new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY!, - }) + }), ); // All operations are now automatically traced @@ -60,65 +60,65 @@ Each operation creates a dedicated span with operation-specific attributes. ### Common Attributes (All Operations) -| Attribute | Description | Example | -| ----------------------- | ----------------------------------- | ------------------ | -| `billing.system` | Constant value `autumn` | `autumn` | -| `billing.operation` | Operation type | `check`, `track` | -| `autumn.resource` | Resource being accessed | `features`, `products` | -| `autumn.target` | Full operation target | `features.check` | -| `autumn.customer_id` | Customer ID | `user_123` | -| `autumn.entity_id` | Entity ID (if applicable) | `org_456` | +| Attribute | Description | Example | +| -------------------- | ------------------------- | ---------------------- | +| `billing.system` | Constant value `autumn` | `autumn` | +| `billing.operation` | Operation type | `check`, `track` | +| `autumn.resource` | Resource being accessed | `features`, `products` | +| `autumn.target` | Full operation target | `features.check` | +| `autumn.customer_id` | Customer ID | `user_123` | +| `autumn.entity_id` | Entity ID (if applicable) | `org_456` | ### Check Operation -| Attribute | Description | Example | -| ------------------------- | --------------------------------- | ------------ | -| `autumn.feature_id` | Feature being checked | `messages` | -| `autumn.product_id` | Product being checked | `pro` | -| `autumn.allowed` | Whether access is allowed | `true` | -| `autumn.balance` | Current balance/remaining uses | `42` | -| `autumn.usage` | Current usage | `8` | -| `autumn.included_usage` | Included usage in plan | `50` | -| `autumn.unlimited` | Whether usage is unlimited | `false` | -| `autumn.required_balance` | Required balance for operation | `1` | +| Attribute | Description | Example | +| ------------------------- | ------------------------------ | ---------- | +| `autumn.feature_id` | Feature being checked | `messages` | +| `autumn.product_id` | Product being checked | `pro` | +| `autumn.allowed` | Whether access is allowed | `true` | +| `autumn.balance` | Current balance/remaining uses | `42` | +| `autumn.usage` | Current usage | `8` | +| `autumn.included_usage` | Included usage in plan | `50` | +| `autumn.unlimited` | Whether usage is unlimited | `false` | +| `autumn.required_balance` | Required balance for operation | `1` | ### Track Operation -| Attribute | Description | Example | -| -------------------------- | ------------------------------ | ----------------- | -| `autumn.feature_id` | Feature being tracked | `messages` | -| `autumn.event_name` | Custom event name | `message_sent` | -| `autumn.value` | Usage value tracked | `1` | -| `autumn.event_id` | Generated event ID | `evt_123` | -| `autumn.idempotency_key` | Idempotency key for dedup | `msg_456` | +| Attribute | Description | Example | +| ------------------------ | ------------------------- | -------------- | +| `autumn.feature_id` | Feature being tracked | `messages` | +| `autumn.event_name` | Custom event name | `message_sent` | +| `autumn.value` | Usage value tracked | `1` | +| `autumn.event_id` | Generated event ID | `evt_123` | +| `autumn.idempotency_key` | Idempotency key for dedup | `msg_456` | ### Checkout Operation -| Attribute | Description | Example | -| --------------------------- | ---------------------------------- | ------------------------- | -| `autumn.product_id` | Product being purchased | `pro` | -| `autumn.product_ids` | Multiple products (comma-separated)| `pro, addon_analytics` | -| `autumn.checkout_url` | Stripe checkout URL | `https://checkout.stripe.com/...` | -| `autumn.has_prorations` | Whether prorations apply | `true` | -| `autumn.total_amount` | Total checkout amount | `2000` (cents) | -| `autumn.currency` | Currency code | `usd` | -| `autumn.force_checkout` | Whether to force Stripe checkout | `false` | -| `autumn.invoice` | Whether to create invoice | `true` | +| Attribute | Description | Example | +| ----------------------- | ----------------------------------- | --------------------------------- | +| `autumn.product_id` | Product being purchased | `pro` | +| `autumn.product_ids` | Multiple products (comma-separated) | `pro, addon_analytics` | +| `autumn.checkout_url` | Stripe checkout URL | `https://checkout.stripe.com/...` | +| `autumn.has_prorations` | Whether prorations apply | `true` | +| `autumn.total_amount` | Total checkout amount | `2000` (cents) | +| `autumn.currency` | Currency code | `usd` | +| `autumn.force_checkout` | Whether to force Stripe checkout | `false` | +| `autumn.invoice` | Whether to create invoice | `true` | ### Attach Operation -| Attribute | Description | Example | -| ------------------------ | ------------------------------- | -------------------------------- | -| `autumn.product_id` | Product being attached | `pro` | -| `autumn.success` | Whether attachment succeeded | `true` | -| `autumn.checkout_url` | Checkout URL if payment needed | `https://checkout.stripe.com/...`| +| Attribute | Description | Example | +| --------------------- | ------------------------------ | --------------------------------- | +| `autumn.product_id` | Product being attached | `pro` | +| `autumn.success` | Whether attachment succeeded | `true` | +| `autumn.checkout_url` | Checkout URL if payment needed | `https://checkout.stripe.com/...` | ### Cancel Operation -| Attribute | Description | Example | -| ---------------------- | -------------------------------- | ---------- | -| `autumn.product_id` | Product being cancelled | `pro` | -| `autumn.success` | Whether cancellation succeeded | `true` | +| Attribute | Description | Example | +| ------------------- | ------------------------------ | ------- | +| `autumn.product_id` | Product being cancelled | `pro` | +| `autumn.success` | Whether cancellation succeeded | `true` | ## Configuration @@ -130,7 +130,7 @@ import { instrumentAutumn } from "@kubiks/otel-autumn"; const autumn = instrumentAutumn(client, { // Capture customer data in spans (default: false) captureCustomerData: true, - + // Capture product options/configuration (default: false) captureOptions: true, }); @@ -141,7 +141,9 @@ const autumn = instrumentAutumn(client, { ### Feature Access Control ```ts -const autumn = instrumentAutumn(new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY! })); +const autumn = instrumentAutumn( + new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY! }), +); // Check if user can access a feature const result = await autumn.check({ @@ -200,25 +202,6 @@ const cancelResult = await autumn.cancel({ }); ``` -## Observability Benefits - -This instrumentation helps you: - -- **Monitor billing operations** - Track success rates, latencies, and errors for all billing calls -- **Debug checkout issues** - See complete checkout flows including prorations and payment failures -- **Analyze feature usage** - Understand which features are being checked and tracked most -- **Track customer journey** - Follow customers through check → track → checkout flows -- **Identify bottlenecks** - Find slow billing operations impacting user experience -- **Audit billing events** - Complete trace of all billing-related operations - -## Best Practices - -1. **Always track server-side** - Use `check` and `track` on the backend for security -2. **Use idempotency keys** - Prevent duplicate tracking with `idempotency_key` -3. **Monitor check failures** - Alert on high rates of `allowed: false` checks -4. **Track checkout abandonment** - Monitor spans where checkout URLs are generated but not completed -5. **Correlate with business metrics** - Link billing spans to revenue and conversion metrics - ## License MIT