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(
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