Onboarding Configuration Guide

This guide explains how to add new data sources to the SigNoz onboarding flow. The onboarding configuration controls the "New Source" / "Get Started" experience in SigNoz Cloud.

Configuration File Location

The configuration is located at:

frontend/src/container/OnboardingV2Container/onboarding-configs/onboarding-config-with-links.ts

Structure Overview

The configuration file exports a TypeScript array (onboardingConfigWithLinks) containing data source objects. Each object represents a selectable option in the onboarding flow. SVG logos are imported as ES modules at the top of the file.

Data Source Object Keys

Required Keys

Key	Type	Description
`dataSource`	`string`	Unique identifier for the data source (kebab-case, e.g., `"aws-ec2"`)
`label`	`string`	Display name shown to users (e.g., `"AWS EC2"`)
`tags`	`string[]`	Array of category tags for grouping (e.g., `["AWS"]`, `["database"]`)
`module`	`string`	Destination module after onboarding completion
`imgUrl`	`string`	Imported SVG URL (SVG required) (e.g., `import ec2Url from '@/assets/Logos/ec2.svg'`, then use `ec2Url`)

Optional Keys

Key	Type	Description
`link`	`string`	Docs link to redirect to (e.g., `"/docs/aws-monitoring/ec2/"`)
`relatedSearchKeywords`	`string[]`	Array of keywords for search functionality
`question`	`object`	Nested question object for multi-step flows
`internalRedirect`	`boolean`	When `true`, navigates within the app instead of showing docs

Module Values

The module key determines where users are redirected after completing onboarding:

Value	Destination
`apm`	APM / Traces
`logs`	Logs Explorer
`metrics`	Metrics Explorer
`dashboards`	Dashboards
`infra-monitoring-hosts`	Infrastructure Monitoring - Hosts
`infra-monitoring-k8s`	Infrastructure Monitoring - Kubernetes
`messaging-queues-kafka`	Messaging Queues - Kafka
`messaging-queues-celery`	Messaging Queues - Celery
`integrations`	Integrations page
`home`	Home page
`api-monitoring`	API Monitoring

Question Object Structure

The question object enables multi-step selection flows:

question: {
  desc: 'What would you like to monitor?',
  type: 'select',
  helpText: 'Choose the telemetry type you want to collect.',
  helpLink: '/docs/azure-monitoring/overview/',
  helpLinkText: 'Read the guide →',
  options: [
    {
      key: 'logging',
      label: 'Logs',
      imgUrl: azureVmUrl,
      link: '/docs/azure-monitoring/app-service/logging/',
    },
    {
      key: 'metrics',
      label: 'Metrics',
      imgUrl: azureVmUrl,
      link: '/docs/azure-monitoring/app-service/metrics/',
    },
    {
      key: 'tracing',
      label: 'Traces',
      imgUrl: azureVmUrl,
      link: '/docs/azure-monitoring/app-service/tracing/',
    },
  ],
},

Question Keys

Key	Type	Description
`desc`	`string`	Question text displayed to the user
`type`	`string`	Currently only `"select"` is supported
`helpText`	`string`	(Optional) Additional help text below the question
`helpLink`	`string`	(Optional) Docs link for the help section
`helpLinkText`	`string`	(Optional) Text for the help link (default: "Learn more →")
`options`	`array`	Array of option objects

Option Object Structure

Options can be simple (direct link) or nested (with another question):

Simple Option (Direct Link)

{
  key: 'aws-ec2-logs',
  label: 'Logs',
  imgUrl: ec2Url,
  link: '/docs/userguide/collect_logs_from_file/',
},

Option with Internal Redirect

{
  key: 'aws-ec2-metrics-one-click',
  label: 'One Click AWS',
  imgUrl: ec2Url,
  link: '/integrations?integration=aws-integration&service=ec2',
  internalRedirect: true,
},

Important: Set internalRedirect: true only for internal app routes (like /integrations?...). Docs links should NOT have this flag.

Nested Option (Multi-step Flow)

{
  key: 'aws-ec2-metrics',
  label: 'Metrics',
  imgUrl: ec2Url,
  question: {
    desc: 'How would you like to set up monitoring?',
    helpText: 'Choose your setup method.',
    options: [...],
  },
},

Examples

Simple Data Source (Direct Link)

import elbUrl from '@/assets/Logos/elb.svg';

// inside the onboardingConfigWithLinks array:
{
  dataSource: 'aws-elb',
  label: 'AWS ELB',
  tags: ['AWS'],
  module: 'logs',
  relatedSearchKeywords: [
    'aws',
    'aws elb',
    'elb logs',
    'elastic load balancer',
  ],
  imgUrl: elbUrl,
  link: '/docs/aws-monitoring/elb/',
},

Data Source with Single Question Level

import azureVmUrl from '@/assets/Logos/azure-vm.svg';

// inside the onboardingConfigWithLinks array:
{
  dataSource: 'app-service',
  label: 'App Service',
  imgUrl: azureVmUrl,
  tags: ['Azure'],
  module: 'apm',
  relatedSearchKeywords: ['azure', 'app service'],
  question: {
    desc: 'What telemetry data do you want to visualise?',
    type: 'select',
    options: [
      {
        key: 'logging',
        label: 'Logs',
        imgUrl: azureVmUrl,
        link: '/docs/azure-monitoring/app-service/logging/',
      },
      {
        key: 'metrics',
        label: 'Metrics',
        imgUrl: azureVmUrl,
        link: '/docs/azure-monitoring/app-service/metrics/',
      },
      {
        key: 'tracing',
        label: 'Traces',
        imgUrl: azureVmUrl,
        link: '/docs/azure-monitoring/app-service/tracing/',
      },
    ],
  },
},

Data Source with Nested Questions (2-3 Levels)

import ec2Url from '@/assets/Logos/ec2.svg';

// inside the onboardingConfigWithLinks array:
{
  dataSource: 'aws-ec2',
  label: 'AWS EC2',
  tags: ['AWS'],
  module: 'logs',
  relatedSearchKeywords: ['aws', 'aws ec2', 'ec2 logs', 'ec2 metrics'],
  imgUrl: ec2Url,
  question: {
    desc: 'What would you like to monitor for AWS EC2?',
    type: 'select',
    helpText: 'Choose the type of telemetry data you want to collect.',
    options: [
      {
        key: 'aws-ec2-logs',
        label: 'Logs',
        imgUrl: ec2Url,
        link: '/docs/userguide/collect_logs_from_file/',
      },
      {
        key: 'aws-ec2-metrics',
        label: 'Metrics',
        imgUrl: ec2Url,
        question: {
          desc: 'How would you like to set up EC2 Metrics monitoring?',
          helpText: 'One Click uses AWS CloudWatch integration. Manual setup uses OpenTelemetry.',
          helpLink: '/docs/aws-monitoring/one-click-vs-manual/',
          helpLinkText: 'Read the comparison guide →',
          options: [
            {
              key: 'aws-ec2-metrics-one-click',
              label: 'One Click AWS',
              imgUrl: ec2Url,
              link: '/integrations?integration=aws-integration&service=ec2',
              internalRedirect: true,
            },
            {
              key: 'aws-ec2-metrics-manual',
              label: 'Manual Setup',
              imgUrl: ec2Url,
              link: '/docs/tutorial/opentelemetry-binary-usage-in-virtual-machine/',
            },
          ],
        },
      },
    ],
  },
},

Best Practices

1. Tags

Use existing tags when possible: AWS, Azure, GCP, database, logs, apm/traces, infrastructure monitoring, LLM Monitoring
Tags are used for grouping in the sidebar
Every data source must have at least one tag

2. Search Keywords

Include variations of the name (e.g., "aws ec2", "ec2", "ec2 logs")
Include common misspellings or alternative names
Keep keywords lowercase and alphabetically sorted

3. Logos

Place logo files in src/assets/Logos/
Use SVG format

Import the SVG at the top of the file and reference the imported variable:

import myServiceUrl from '@/assets/Logos/my-service.svg';
// then in the config object:
imgUrl: myServiceUrl,

Fetching Icons: New icons can be easily fetched from OpenBrand. Use the pattern https://openbrand.sh/?url=<TARGET_URL>, where <TARGET_URL> is the URL-encoded link to the service's website. For example, to get Render's logo, use https://openbrand.sh/?url=https%3A%2F%2Frender.com.
Optimize new SVGs: Run any newly downloaded SVGs through an optimizer like SVGOMG (svgo) or use npx svgo src/assets/Logos/your-logo.svg to minimise their size before committing.

4. Links

Docs links should start with /docs/ (will be prefixed with DOCS_BASE_URL)
Internal app links should start with /integrations, /services, etc.
Only use internalRedirect: true for internal app routes

5. Keys

Use kebab-case for dataSource and option key values
Make keys descriptive and unique
Follow the pattern: {service}-{subtype}-{action} (e.g., aws-ec2-metrics-one-click)

Adding a New Data Source

Add the logo SVG to src/assets/Logos/ and add a top-level import in the config file (e.g., import myServiceUrl from '@/assets/Logos/my-service.svg')
Add your data source object to the onboardingConfigWithLinks array, referencing the imported variable for imgUrl
Test the flow locally with yarn dev
Validation:
- Navigate to the onboarding page on your local machine
- Data source appears in the list
- Search keywords work correctly
- All links redirect to the correct pages
- Questions display correct help text and links
- Tags are used for grouping in the UI sidebar
- Clicking on Configure redirects to the correct page