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

# Tsuga

> Import metrics, logs, and traces from Tsuga into Costory

Connect Tsuga usage metrics to Costory when you want to divide cloud cost by requests, errors, latency, or another telemetry signal. Costory imports Tsuga metrics, log aggregations, and trace aggregations so you can build <Tooltip tip="Financial metrics expressed on a per-unit basis, such as cost per customer, cost per API call, or cost per transaction." cta="See Glossary" href="/docs/glossary#unit-economics">unit economics</Tooltip> reports from the same data you use for observability.

<Check>
  Before you begin, make sure you have:

  * A **Tsuga account** with at least one metric, log stream, or trace
  * Permissions to create **Operation API Keys** in your Tsuga workspace
</Check>

## What You Provide

<CardGroup cols={2}>
  <Card title="Operation API Key" icon="key">
    A Bearer token scoped to read metrics and run aggregations.
  </Card>

  <Card title="Metric or Query Config" icon="chart-line">
    The metric names and aggregation you want to import.
  </Card>
</CardGroup>

## Setup Steps

<Steps>
  <Step title="Create an Operation API Key in Tsuga">
    Go to [Settings > API Keys](https://app.tsuga.com/settings/api-keys?operation=true) in the Tsuga app and create a new key with the **Operation** type. Copy the key. It is only shown once.
  </Step>

  <Step title="Add Tsuga as a data source in Costory">
    Navigate to **Settings > Data Sources > Add New** and select **Tsuga**.
  </Step>

  <Step title="Enter your API key">
    Paste your Operation API Key. Costory uses it as a Bearer token against `https://api.tsuga.com`.
  </Step>

  <Step title="Browse available metrics">
    Costory calls `GET /v1/metrics` to list all metrics in your workspace. Select the metrics you want to import.
  </Step>

  <Step title="Configure your aggregation">
    For each metric, choose an aggregation type: `sum`, `average`, `max`, `min`, `count`, or `percentile`. You can also add an optional group-by field, such as `service` or `env`.
  </Step>

  <Step title="Set the import schedule">
    Choose how often Costory should pull updated data. Daily imports are recommended for cost correlation.
  </Step>
</Steps>

## How Costory Queries Tsuga

Costory uses two Tsuga endpoints depending on the chart type:

| Use case                              | Endpoint                                      |
| ------------------------------------- | --------------------------------------------- |
| Single aggregated value over a period | `POST /v1/aggregation/multi-query/scalar`     |
| Time series for trend charts          | `POST /v1/aggregation/multi-query/timeseries` |

Both endpoints support `metrics`, `logs`, and `traces` as data sources. You can import raw metrics or aggregations derived from logs and traces, such as HTTP errors per minute from logs or p99 latency from traces.

### Example: query API call count as a time series

```http theme={null}
POST https://api.tsuga.com/v1/aggregation/multi-query/timeseries
Authorization: Bearer <your-operation-api-key>

{
  "dataSource": "metrics",
  "timeRange": { "from": 1704067200, "to": 1706745600 },
  "aggregationWindow": "1h",
  "queries": [
    {
      "aggregate": { "type": "sum", "metric": "http.request.count" }
    }
  ],
  "groupBy": [
    { "fields": ["service"], "limit": 20 }
  ]
}
```

## Supported Data Sources

<CardGroup cols={3}>
  <Card title="Metrics" icon="gauge">
    Standard time series metrics, including counters, gauges, and histograms.
  </Card>

  <Card title="Logs" icon="file-lines">
    Aggregations computed from log streams, such as error rate.
  </Card>

  <Card title="Traces" icon="diagram-project">
    Aggregations computed from distributed traces, such as p99 latency.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is an Operation API Key?">
    Tsuga has two key types: Ingestion keys are write-only and send data to Tsuga. Operation keys are read-only and query data. Costory needs an Operation key to call the public API.
  </Accordion>

  <Accordion title="Can I import metrics derived from logs or traces, not just raw metrics?">
    Yes. The aggregation endpoints support `"dataSource": "logs"` and `"dataSource": "traces"`. You can define any aggregation Tsuga supports, and Costory treats the result as a usage metric.
  </Accordion>

  <Accordion title="Can I filter by a specific service or environment?">
    Yes. Use the `filter` field in the query body with Tsuga's query syntax, such as `service:my-service AND env:production`, to scope the metric to part of your infrastructure.
  </Accordion>

  <Accordion title="How do I find the metric names available in my workspace?">
    Tsuga's `GET /v1/metrics` endpoint returns all metric names with their metadata. You can also browse the API reference at [app.tsuga.com/swagger](https://app.tsuga.com/swagger).
  </Accordion>

  <Accordion title="When will I see data in Costory after setup?">
    You typically see data within a few minutes of the first successful sync. Historical backfill depends on the retention configured in your Tsuga workspace.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Build Unit Economics" icon="calculator" href="/automate-reporting/unit-economics">
    Divide cloud costs by Tsuga metrics to track cost per request, cost per user, and other per-unit metrics.
  </Card>

  <Card title="Connect Events" icon="calendar" href="/setup/events">
    Add deploys and incidents to correlate with metric changes.
  </Card>
</CardGroup>