zoriya/drizzle-otel
1
0
Fork 0
mirror of https://github.com/zoriya/drizzle-otel.git synced 2025-12-06 00:46:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Alex Holovach
2025-10-09 23:44:56 -05:00
parent b34b3e002b
commit cebe224bcd
1 changed files with 49 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
packages/otel-autumn/README.md
View File

@@ -26,7 +26,7 @@ import { instrumentAutumn } from "@kubiks/otel-autumn";
const autumn = instrumentAutumn( const autumn = instrumentAutumn(
new Autumn({ new Autumn({
secretKey: process.env.AUTUMN_SECRET_KEY!, secretKey: process.env.AUTUMN_SECRET_KEY!,
}) }),
); );
// All operations are now automatically traced // All operations are now automatically traced
@@ -60,65 +60,65 @@ Each operation creates a dedicated span with operation-specific attributes.
### Common Attributes (All Operations) ### Common Attributes (All Operations)
| Attribute | Description | Example | | Attribute | Description | Example |
| ----------------------- | ----------------------------------- | ------------------ | | -------------------- | ------------------------- | ---------------------- |
| `billing.system` | Constant value `autumn` | `autumn` | | `billing.system` | Constant value `autumn` | `autumn` |
| `billing.operation` | Operation type | `check`, `track` | | `billing.operation` | Operation type | `check`, `track` |
| `autumn.resource` | Resource being accessed | `features`, `products` | | `autumn.resource` | Resource being accessed | `features`, `products` |
| `autumn.target` | Full operation target | `features.check` | | `autumn.target` | Full operation target | `features.check` |
| `autumn.customer_id` | Customer ID | `user_123` | | `autumn.customer_id` | Customer ID | `user_123` |
| `autumn.entity_id` | Entity ID (if applicable) | `org_456` | | `autumn.entity_id` | Entity ID (if applicable) | `org_456` |
### Check Operation ### Check Operation
| Attribute | Description | Example | | Attribute | Description | Example |
| ------------------------- | --------------------------------- | ------------ | | ------------------------- | ------------------------------ | ---------- |
| `autumn.feature_id` | Feature being checked | `messages` | | `autumn.feature_id` | Feature being checked | `messages` |
| `autumn.product_id` | Product being checked | `pro` | | `autumn.product_id` | Product being checked | `pro` |
| `autumn.allowed` | Whether access is allowed | `true` | | `autumn.allowed` | Whether access is allowed | `true` |
| `autumn.balance` | Current balance/remaining uses | `42` | | `autumn.balance` | Current balance/remaining uses | `42` |
| `autumn.usage` | Current usage | `8` | | `autumn.usage` | Current usage | `8` |
| `autumn.included_usage` | Included usage in plan | `50` | | `autumn.included_usage` | Included usage in plan | `50` |
| `autumn.unlimited` | Whether usage is unlimited | `false` | | `autumn.unlimited` | Whether usage is unlimited | `false` |
| `autumn.required_balance` | Required balance for operation | `1` | | `autumn.required_balance` | Required balance for operation | `1` |
### Track Operation ### Track Operation
| Attribute | Description | Example | | Attribute | Description | Example |
| -------------------------- | ------------------------------ | ----------------- | | ------------------------ | ------------------------- | -------------- |
| `autumn.feature_id` | Feature being tracked | `messages` | | `autumn.feature_id` | Feature being tracked | `messages` |
| `autumn.event_name` | Custom event name | `message_sent` | | `autumn.event_name` | Custom event name | `message_sent` |
| `autumn.value` | Usage value tracked | `1` | | `autumn.value` | Usage value tracked | `1` |
| `autumn.event_id` | Generated event ID | `evt_123` | | `autumn.event_id` | Generated event ID | `evt_123` |
| `autumn.idempotency_key` | Idempotency key for dedup | `msg_456` | | `autumn.idempotency_key` | Idempotency key for dedup | `msg_456` |
### Checkout Operation ### Checkout Operation
| Attribute | Description | Example | | Attribute | Description | Example |
| --------------------------- | ---------------------------------- | ------------------------- | | ----------------------- | ----------------------------------- | --------------------------------- |
| `autumn.product_id` | Product being purchased | `pro` | | `autumn.product_id` | Product being purchased | `pro` |
| `autumn.product_ids` | Multiple products (comma-separated)| `pro, addon_analytics` | | `autumn.product_ids` | Multiple products (comma-separated) | `pro, addon_analytics` |
| `autumn.checkout_url` | Stripe checkout URL | `https://checkout.stripe.com/...` | | `autumn.checkout_url` | Stripe checkout URL | `https://checkout.stripe.com/...` |
| `autumn.has_prorations` | Whether prorations apply | `true` | | `autumn.has_prorations` | Whether prorations apply | `true` |
| `autumn.total_amount` | Total checkout amount | `2000` (cents) | | `autumn.total_amount` | Total checkout amount | `2000` (cents) |
| `autumn.currency` | Currency code | `usd` | | `autumn.currency` | Currency code | `usd` |
| `autumn.force_checkout` | Whether to force Stripe checkout | `false` | | `autumn.force_checkout` | Whether to force Stripe checkout | `false` |
| `autumn.invoice` | Whether to create invoice | `true` | | `autumn.invoice` | Whether to create invoice | `true` |
### Attach Operation ### Attach Operation
| Attribute | Description | Example | | Attribute | Description | Example |
| ------------------------ | ------------------------------- | -------------------------------- | | --------------------- | ------------------------------ | --------------------------------- |
| `autumn.product_id` | Product being attached | `pro` | | `autumn.product_id` | Product being attached | `pro` |
| `autumn.success` | Whether attachment succeeded | `true` | | `autumn.success` | Whether attachment succeeded | `true` |
| `autumn.checkout_url` | Checkout URL if payment needed | `https://checkout.stripe.com/...`| | `autumn.checkout_url` | Checkout URL if payment needed | `https://checkout.stripe.com/...` |
### Cancel Operation ### Cancel Operation
| Attribute | Description | Example | | Attribute | Description | Example |
| ---------------------- | -------------------------------- | ---------- | | ------------------- | ------------------------------ | ------- |
| `autumn.product_id` | Product being cancelled | `pro` | | `autumn.product_id` | Product being cancelled | `pro` |
| `autumn.success` | Whether cancellation succeeded | `true` | | `autumn.success` | Whether cancellation succeeded | `true` |
## Configuration ## Configuration
@@ -130,7 +130,7 @@ import { instrumentAutumn } from "@kubiks/otel-autumn";
const autumn = instrumentAutumn(client, { const autumn = instrumentAutumn(client, {
// Capture customer data in spans (default: false) // Capture customer data in spans (default: false)
captureCustomerData: true, captureCustomerData: true,
// Capture product options/configuration (default: false) // Capture product options/configuration (default: false)
captureOptions: true, captureOptions: true,
}); });
@@ -141,7 +141,9 @@ const autumn = instrumentAutumn(client, {
### Feature Access Control ### Feature Access Control
```ts ```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 // Check if user can access a feature
const result = await autumn.check({ 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 ## License
MIT MIT