> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 时间范围蓝图

> 根据计算、无服务器函数、容器和运行时计费的经过时间跟踪资源消耗。

## 用例

探索时间范围蓝图支持的常见场景：

<CardGroup cols={2}>
  <Card title="Serverless Functions" icon="function">
    根据函数执行时间和内存使用量计费。
  </Card>

  <Card title="Container Runtime" icon="container-storage">
    跟踪容器运行时间以实现基于使用量的计费。
  </Card>

  <Card title="Compute Instances" icon="server">
    监控虚拟机运行时间，按分钟或小时收费。
  </Card>

  <Card title="Background Jobs" icon="briefcase">
    跟踪数据导出、报告和批处理作业的处理时间。
  </Card>
</CardGroup>

<Info>
  非常适合基于计算时间、函数执行时长、容器运行时间或任何基于时间的使用情况进行计费。
</Info>

## 快速开始

按时间持续时间跟踪资源使用：

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    * **Dodo Payments API Key**：请从 [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys) 获取
  </Step>

  <Step title="Create a Meter">
    在 [Dodo Payments Dashboard](https://app.dodopayments.com/) 中创建一个计量器：

    * **Event Name**：`time_range_usage`（或您喜欢的名称）
    * **Aggregation Type**：`sum` 以跟踪总时长
    * **Over Property**：`durationSeconds`、`durationMinutes` 或 `durationMs`
  </Step>

  <Step title="Track Time Usage">
    <CodeGroup>
      ```javascript Serverless Functions theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'function_execution'
      });

      // Track function execution time
      const startTime = Date.now();

      // Execute your function (example: image processing)
      const result = await yourImageProcessingLogic();

      const durationMs = Date.now() - startTime;

      await trackTimeRange(ingestion, {
        customerId: 'customer_123',
        durationMs: durationMs
      });
      ```

      ```javascript Container Runtime theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'container_runtime'
      });

      // Track container runtime in seconds
      await trackTimeRange(ingestion, {
        customerId: 'customer_456',
        durationSeconds: 120
      });
      ```

      ```javascript VM Instance Runtime theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'vm_runtime'
      });

      // Track VM runtime in minutes
      await trackTimeRange(ingestion, {
        customerId: 'customer_789',
        durationMinutes: 60
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## 配置

### 数据摄取配置

<ParamField path="apiKey" type="string" required>
  来自仪表板的 Dodo Payments API 密钥。
</ParamField>

<ParamField path="environment" type="string" required>
  环境模式：`test_mode` 或 `live_mode`。
</ParamField>

<ParamField path="eventName" type="string" required>
  与您的计量器配置匹配的事件名称。
</ParamField>

### 跟踪时间范围选项

<ParamField path="customerId" type="string" required>
  用于计费归属的客户 ID。
</ParamField>

<ParamField path="durationMs" type="number">
  以毫秒为单位的持续时间。用于亚秒级精度。
</ParamField>

<ParamField path="durationSeconds" type="number">
  以秒为单位的持续时间。最常用于函数执行和短任务。
</ParamField>

<ParamField path="durationMinutes" type="number">
  以分钟为单位的持续时间。适用于运行时间较长的资源，例如虚拟机。
</ParamField>

<ParamField path="metadata" type="object">
  有关资源的可选元数据，例如 CPU、内存、区域等。
</ParamField>

## 最佳实践

<Tip>
  **选择合适的单位**：短操作使用毫秒，函数使用秒，运行时间较长的资源使用分钟。
</Tip>

<Warning>
  **精准计时**：使用 `Date.now()` 或 `performance.now()` 以实现准确的时间跟踪，特别是用于无服务器函数。
</Warning>