|
| 1 | +--- |
| 2 | +description: >- |
| 3 | + You can craft your own custom installation of OpenTelemetry NodeJS SDK and |
| 4 | + integrate Aspecto Sampler to benefit from advanced sampling capabilities. |
| 5 | +--- |
| 6 | + |
| 7 | +# Aspecto Sampler |
| 8 | + |
| 9 | +Aspecto sampler fetches remote sampling rules that you configure in Aspecto platform and applies them on traces that start in a given service. |
| 10 | + |
| 11 | +### Install |
| 12 | + |
| 13 | +npm |
| 14 | + |
| 15 | +```bash |
| 16 | +npm install @aspecto/opentelemetry-sampler |
| 17 | +``` |
| 18 | + |
| 19 | +yarn |
| 20 | + |
| 21 | +```bash |
| 22 | +yarn add @aspecto/opentelemetry-sampler |
| 23 | +``` |
| 24 | + |
| 25 | +### Usage |
| 26 | + |
| 27 | +Create an instance of `AspectoSampler` and use it in your `TracerProvider` |
| 28 | + |
| 29 | +{% tabs %} |
| 30 | +{% tab title="Type Script" %} |
| 31 | +```typescript |
| 32 | +import { AspectoSampler } from '@aspecto/opentelemetry-sampler'; |
| 33 | + |
| 34 | +// create an instance of AspectoSampler |
| 35 | +const aspectoSampler = new AspectoSampler({ |
| 36 | + // aspectoAuth, |
| 37 | + // serviceName, |
| 38 | + // env, |
| 39 | + // requireConfigForTraces, |
| 40 | + // samplingRatio, |
| 41 | +}); |
| 42 | + |
| 43 | +// Now, you can now use it wherever an OpenTelemetry sampler is acceptable |
| 44 | + |
| 45 | +// NodeTracerProvider |
| 46 | +import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'; |
| 47 | +const provider = new NodeTracerProvider({ |
| 48 | + sampler: aspectoSampler, |
| 49 | +}); |
| 50 | + |
| 51 | +// NodeSDK |
| 52 | +import { NodeSDK } from '@opentelemetry/sdk-node'; |
| 53 | +const sdk = new NodeSDK({ |
| 54 | + traceExporter: // add your trace exporter here |
| 55 | + sampler: aspectoSampler, |
| 56 | +}); |
| 57 | +``` |
| 58 | +{% endtab %} |
| 59 | + |
| 60 | +{% tab title="Java Script" %} |
| 61 | +```javascript |
| 62 | +const { AspectoSampler } = require('@aspecto/opentelemetry-sampler'); |
| 63 | + |
| 64 | +// create an instance of AspectoSampler |
| 65 | +const aspectoSampler = new AspectoSampler({ |
| 66 | + // aspectoAuth, |
| 67 | + // serviceName, |
| 68 | + // env, |
| 69 | + // requireConfigForTraces, |
| 70 | + // samplingRatio, |
| 71 | +}); |
| 72 | + |
| 73 | +// Now, you can now use it wherever an OpenTelemetry sampler is acceptable |
| 74 | + |
| 75 | +// NodeTracerProvider |
| 76 | +const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node'); |
| 77 | +const provider = new NodeTracerProvider({ |
| 78 | + sampler: aspectoSampler, |
| 79 | +}); |
| 80 | + |
| 81 | +// BasicTracerProvider |
| 82 | +const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base'); |
| 83 | +const provider = new BasicTracerProvider({ |
| 84 | + sampler: aspectoSampler, |
| 85 | +}); |
| 86 | +``` |
| 87 | +{% endtab %} |
| 88 | +{% endtabs %} |
| 89 | + |
| 90 | +### Configuration |
| 91 | + |
| 92 | +You can configure the sampler via one or more of the following: |
| 93 | + |
| 94 | +* `options` variable. for example: `new AspectoSampler({optionName: optionValue})`. This enables setting config options dynamically. |
| 95 | +* Environment variables |
| 96 | +* Add `aspecto.json` configuration file to the root directory, next to service's `package.json` file |
| 97 | + |
| 98 | +Values are evaluated in the following priority: |
| 99 | + |
| 100 | +1. `options` object |
| 101 | +2. environment variables |
| 102 | +3. config file |
| 103 | +4. default values |
| 104 | + |
| 105 | +Aspecto auth is required. Service name and env are recommended. |
| 106 | + |
| 107 | +| Option Name | Environment Variable | Type | Default | Description | |
| 108 | +| ------------------------ | ----------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 109 | +| `disableAspecto` | `DISABLE_ASPECTO` | boolean | `false` | Disable the sampler and don't apply any sampling logic (sample nothing) | |
| 110 | +| `aspectoAuth` | `ASPECTO_AUTH` | UUID | - | [Aspecto token](https://app.aspecto.io/app/integration/api-key) for authentication to read sampling configuration | |
| 111 | +| `env` | `NODE_ENV` | string | - | Set environment for matching sampling rules | |
| 112 | +| `serviceName` | `OTEL_SERVICE_NAME` | string | - | Set service name for matching sampling rules | |
| 113 | +| `samplingRatio` | `ASPECTO_SAMPLING_RATIO` | number | `1.0` | This option is used as a fallback if no specific sampling rule is matched, and before remote sampling rule configuration is fetched. It controls how many of the traces starting in this service should be sampled. Set to number in range the \[0.0, 1.0] where `0.0` is no sampling, and `1.0` is sample all. | |
| 114 | +| `requireConfigForTraces` | `ASPECTO_REQUIRE_CONFIG_FOR_TRACES` | boolean | `false` | When `true`, the Sampler will not trace anything until the remote sampling configuration arrives (a few hundred ms). Can be used to enforce sampling configuration is always applied, with the cost of losing traces generated during service startup. | |
0 commit comments