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

# Honeycomb Refinery

> Deploy and operate Refinery, Honeycomb's trace-aware, tail-based sampling proxy. Set up your cluster, define sampling rules, and monitor performance.

export const HnyIcon = ({alias, path, size = 16, iconColor}) => {
  const iconMap = {
    "home": "house.svg",
    "marker": "caretFilledDown.svg",
    "show-marker-options": "chatTextLeft.svg",
    "download": "arrowLineDown.svg",
    "trace-waterfall": "trace.svg",
    "show-query-details": "listDashes.svg",
    "table": "table.svg",
    "log-lines": "logLines.svg",
    "chart": "chartLine.svg",
    "show-settings": "gear.svg",
    "add": "plus.svg",
    "remove": "delete.svg",
    "persist": "caretDown.svg",
    "close": "close.svg",
    "copy": "copy.svg",
    "zoom-in": "magnifyingGlassPlus.svg",
    "zoom-out": "magnifyingGlassMinus.svg",
    "color-assignment": "drop.svg",
    "drag": "dots-six-vertical.svg",
    "drawer": "drawer.svg",
    "show-actions": "dotsThree.svg",
    "edit": "pencil.svg",
    "delete": "trash.svg",
    "move": "arrowsOutCardinal.svg",
    "show-legend": "circleInfo.svg",
    "usage-ok": "usageGood.svg",
    "usage-warning": "usageWarning.svg",
    "usage-danger": "usageDanger.svg",
    "open-query-builder": "query.svg",
    "home-menu": "house.svg",
    "query-menu": "query.svg",
    "boards-menu": "board.svg",
    "triggers-menu": "bell.svg",
    "slos-menu": "handshake.svg",
    "service-map-menu": "serviceMap.svg",
    "history-menu": "clockCounterClockwise.svg",
    "manage-data-menu": "cube.svg",
    "usage-menu": "usageGood.svg",
    "show-details": "dotsThreeVertical.svg",
    "resize-handle": "board-panel-resize-handle.png",
    "standard-dataset": "cube.svg",
    "trace-dataset": "cubeChat.svg",
    "all-datasets": "linkedSquares.svg",
    "share": "arrowBentRight.svg",
    "run-in-query-builder": "arrowSquareUpRight.svg",
    "link": "link.svg",
    "text": "text.svg",
    "receive": "arrowLineDown.svg",
    "process": "lightning.svg",
    "sample": "drop.svg",
    "send": "arrowLineUp.svg",
    "submit": "arrowUp.svg",
    "canvas-menu": "sparkle.svg",
    "canvas": "sparkle.svg",
    "private": "lockKey.svg",
    "shared": "people.svg",
    "expand": "caretDown.svg",
    "previous": "caretLeft.svg",
    "next": "caretRight.svg"
  };
  const iconBasePath = "/_assets/icons/";
  const iconPath = path || (alias ? `${iconBasePath}${iconMap[alias]}` : undefined);
  return <span className="hny-icon" style={{
    display: "inline-block",
    width: `${size}px`,
    height: `${size}px`,
    maskImage: `url(${iconPath})`,
    maskSize: "contain",
    maskRepeat: "no-repeat",
    maskPosition: "center",
    WebkitMaskImage: `url(${iconPath})`,
    WebkitMaskSize: "contain",
    WebkitMaskRepeat: "no-repeat",
    WebkitMaskPosition: "center",
    backgroundColor: iconColor || "var(--hny-icon-color)",
    verticalAlign: "middle"
  }} />;
};

export const CalloutLearn = ({children}) => {
  return <Callout icon="brain-circuit" color="#8B5CF6">
      {children}
    </Callout>;
};

<Info>
  This documentation reflects Honeycomb Refinery 3.0, the latest major release.

  If you're using a previous version of Refinery, we recommend that you [migrate to Refinery 3.0 or later](/troubleshoot/product-lifecycle/recommended-migrations/upgrade-refinery/) to take advantage of new and improved features.
</Info>

Refinery is a tail-based sampling proxy and operates at the level of an entire [trace](/get-started/basics/observability/concepts/distributed-tracing/).

Refinery examines whole traces and intelligently applies sampling decisions to each trace.
These decisions determine whether to include or discard the trace data in the sampled data sent to Honeycomb.

A tail-based sampling model lets you inspect an entire trace at one time and make a decision to sample based on its contents.
For example, your data may have a root span with the HTTP status code to serve for a request, and another span with information on whether the data was served from a cache.
Using Refinery, you can choose to keep only traces that had a `500` status code and were also served from a cache.

<CalloutLearn>
  For more structured learning, check out the <HnyIcon path="/_assets/icons/phosphor/Certificate.svg" /> [Introduction to Refinery](https://academy.honeycomb.io/app/courses/96b6353d-28da-4b73-9a45-e72db585cb7a) course from Honeycomb Academy.
</CalloutLearn>

## Refinery's tail-based sampling capabilities

Refinery support several kinds of tail sampling:

* **Dynamic sampling** - This sampling type configures a key based on a trace's set of fields and automatically increases or decreases the sampling rate based on how frequently each unique value of that key occurs. For example, using a key based on `http.status_code`, you can include in your sampled data:
  * one out of every 1,000 traces for requests that return `2xx`
  * one out of every 10 traces for requests that return `4xx`
  * every request that returns `5xx`
* **Rules-based sampling** - This sampling type enables you to define sampling rates for well-known conditions. For example, in your sampled data, you can keep 100% of traces with an error and then apply dynamic sampling to all other traffic.
* **Throughput-based sampling** - This sampling type enables you to sample traces based on a fixed upper-bound for the number of spans per second. The sampler will dynamically sample traces with a goal of keeping the throughput below the specified limit.
* **Deterministic probability sampling** - This sampling type consistently applies sampling decisions without considering the contents of the trace other than its trace ID. For example, you can include 1 out of every 12 traces in the sampled data sent to Honeycomb. This kind of sampling can also be done using [head sampling](/manage-data-volume/sample/#head-sampling), and if you use both, Refinery takes that into account.
* **Supports OpenTelemetry traces and logs signals** - Handles both OpenTelemetry trace and log data signals. Log records associated with traces are sampled as part of the trace. Unassociated log events are forwarded directly to Honeycomb.

Refinery lets you combine all of the above techniques to achieve your desired sampling behavior.

## Next Steps

Explore our [Refinery setup instructions](/manage-data-volume/sample/honeycomb-refinery/set-up/).

The default configuration at installation contains the minimum configuration needed to run Refinery.
Customize your configuration with [general configuration](/manage-data-volume/sample/honeycomb-refinery/configure/) and [sampling method configuration](/manage-data-volume/sample/honeycomb-refinery/sampling-methods/).

While configuring, you may need to [scale](/manage-data-volume/sample/honeycomb-refinery/scale-size/) and [troubleshoot](/troubleshoot/common-issues/refinery/) your Refinery instance.