railigentxotelreceiver

README

RailigentX Receiver

This project provides an OpenTelemetry receiver that scrapes metrics from the RailigentX API and sends them to a OpenTelemetry Collector.

Table of Contents

• Overview
• Features
• Installation
• Configuration
• Logging
• Contributing
• License

Overview

The RailigentX Receiver is a component for the OpenTelemetry Collector that collects metrics from the RailigentX API.

It scrapes data from RailigentX at specified intervals and transforms the data into OpenTelemetry metrics which are then consumed by the Collector.

Features

• Scrapes asset metrics such as GPS location, mileage, and speed from RailigentX (more TODO).
• Periodic scraping at user-defined intervals.
• Configurable logging for monitoring and debugging.

Installation

To build a custom collector that includes the RailigentX receiver, you can use the following builder-config.yaml configuration (eg here to scrape railigentx metrics and export them with prometheus):

dist:
  name: custom-otelcol
  description: "Custom OpenTelemetry Collector with RailigentX Receiver"
  output_path: ./dist

receivers:
  - gomod:
      github.com/skilld-labs/railigentxotelreceiver v1.0.10

exporters:
  - gomod:
      github.com/open-telemetry/opentelemetry-collector-contrib/exporter/prometheusexporter v0.100.0

To build and run the custom collector:

1. Install the OpenTelemetry Collector builder:

   go install go.opentelemetry.io/collector/cmd/builder@latest
   

   Click here for more details

2. Create the custom collector using the builder configuration:

   builder --config builder-config.yaml
   

3. Create a configuration file config.yaml for the collector see instructions

4. Run the custom collector:

   ./dist/custom-otelcol --config config.yaml
   

Configuration

The receiver requires a configuration file to specify settings such as the RailigentX API credentials, scrape interval, and logging level. Below is an example configuration file:

receivers:
  railigentx:
    base_url: "https://api.railigentx.com"
    username: yourusername
    password: yourpassword
    scrapeInterval: 10s
    asset_metric_repository:
      name: bbolt
      config:
        db_path: /tmp/db

exporters:
  prometheus:
    endpoint: "0.0.0.0:9090"
    resource_to_telemetry_conversion:
      enabled: true

service:
  pipelines:
    metrics:
      receivers: [railigentx]
      exporters: [prometheus]
  telemetry:
    logs:
      level: debug

Configuration Options

• base_url: The RailigentX API base URL.
• username: Your RailigentX username.
• password: Your RailigentX password.
• scrape_interval: The interval at which the receiver scrapes metrics from RailigentX (e.g., 60s for 60 seconds).
• asset_metric_repository: This is the configuration for keeping metrics timestamps informations and avoid sending multiple times metrics points that have already been collected. There are currently two implementations: inmem and bbolt.

Inmem Repository

The Inmem repository will keep metrics timestamps in memory. It doesn't require any storage space, but as a side effect, it could send multiple times the same metrics informations in case of restart of the application.

Bbolt Repository

The Bbolt repository will keep metrics timestamps in a dedicated db file. In case of application restart, it will use this database to know if metrics has been already send or not. Configuration:

• db_path: The path of the file where database will be stored.

Logging

The receiver uses the zap logger for logging. The logging configuration can be adjusted in the configuration file. The logs provide detailed information about the lifecycle of the receiver, the scraping process, and any errors encountered.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub. Ensure your code adheres to the project's coding standards and includes appropriate tests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Index

• func NewBboltAssetMetricRepoConfig() interface{}
• func NewFactory() receiver.Factory
• func NewInmemAssetMetricRepoConfig() interface{}
• type AssetMetric
  • func (am *AssetMetric) Signature() string
• type AssetMetricRepository
  • func NewBboltAssetMetricRepo(config interface{}) (AssetMetricRepository, error)
  • func NewInmemAssetMetricRepo(config interface{}) (AssetMetricRepository, error)
• type AssetMetricRepositoryConfig
• type Config
  • func (cfg *Config) Validate() error
• type FleetObservations
• type ScrapeState
• type ScrapedData

Functions

func NewBboltAssetMetricRepoConfig

func NewBboltAssetMetricRepoConfig() interface{}

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for tailtracer receiver.

func NewInmemAssetMetricRepoConfig

func NewInmemAssetMetricRepoConfig() interface{}

Types

type AssetMetric

type AssetMetric struct {
	Asset  string
	Metric string
}

func (*AssetMetric) Signature

func (am *AssetMetric) Signature() string

type AssetMetricRepository

type AssetMetricRepository interface {
	Store(*AssetMetric, time.Time) error
	Get(*AssetMetric) (time.Time, bool, error)
}

func NewBboltAssetMetricRepo

func NewBboltAssetMetricRepo(config interface{}) (AssetMetricRepository, error)

func NewInmemAssetMetricRepo

func NewInmemAssetMetricRepo(config interface{}) (AssetMetricRepository, error)

type AssetMetricRepositoryConfig

type AssetMetricRepositoryConfig struct {
	Name   string      `mapstructure:"name"`
	Config interface{} `mapstructure:"config"`
}

type Config

type Config struct {
	BaseURL               string                      `mapstructure:"base_url"`
	Username              string                      `mapstructure:"username"`
	Password              string                      `mapstructure:"password"`
	ScrapeInterval        time.Duration               `mapstructure:"scrape_interval"`
	AssetMetricRepository AssetMetricRepositoryConfig `mapstructure:"asset_metric_repository"`
}

func (*Config) Validate

func (cfg *Config) Validate() error

type FleetObservations

type FleetObservations struct {
	Fleet        string
	Observed     bool
	Observations []railigentx.Asset
}

FleetObservations holds observations for a fleet

type ScrapeState

type ScrapeState int

const (
	ScrapeSucceeded ScrapeState = iota
	ScrapeFailed
	ScrapeIncomplete
)

type ScrapedData

type ScrapedData struct {
	ObservedAt         time.Time
	FleetsObservations []FleetObservations
}

ScrapedData holds data scraped from RailigentX