callhome

README

Magistrala Callhome Service

This is a server to receive and store information regarding Magistrala deployments.

The summary is located on our Website.

Usage

To Run:

make docker-image
make run

Requirements

• IP to Location database

Data Collection for Magistrala

Magistrala is committed to continuously improving its services and ensuring a seamless experience for its users. To achieve this, we collect certain data from your deployments. Rest assured, this data is collected solely for the purpose of enhancing Magistrala and is not used with any malicious intent. The deployment summary can be found on our website.

The collected data includes:

• IP Address - Used for approximate location information on deployments.
• Services Used - To understand which features are popular and prioritize future developments.
• Last Seen Time - To ensure the stability and availability of Magistrala.
• Magistrala Version - To track the software version and deliver relevant updates.

We take your privacy and data security seriously. All data collected is handled in accordance with our stringent privacy policies and industry best practices.

Data collection is on by default and can be disabled by setting the env variable: MF_SEND_TELEMETRY=false

By utilizing Magistrala, you actively contribute to its improvement. Together, we can build a more robust and efficient IoT platform. Thank you for your trust in Magistrala!

Documentation

Index

• type CountrySummary
• type LocationService
  • func NewLocationService(dbfilepath string) (LocationService, error)
• type PageMetadata
• type Service
  • func New(repo TelemetryRepo, locSvc LocationService) Service
• type Telemetry
• type TelemetryFilters
• type TelemetryPage
• type TelemetryRepo
• type TelemetrySummary

Types

type CountrySummary

type CountrySummary struct {
	Country       string `json:"country" db:"country"`
	NoDeployments int    `json:"number_of_deployments" db:"count"`
}

type LocationService

type LocationService interface {
	// GetLocation returns the location information for a given IP address.
	GetLocation(ctx context.Context, ip string) (ip2location.IP2Locationrecord, error)
}

LocationService provides a service for obtaining location information from an IP address.

func NewLocationService

func NewLocationService(dbfilepath string) (LocationService, error)

NewLocationService creates a new LocationService that uses the specified IP2Location database file.

type PageMetadata

type PageMetadata struct {
	Total  uint64
	Offset uint64
	Limit  uint64
}

type Service

type Service interface {
	// Save saves the homing telemetry data and its location information.
	Save(ctx context.Context, t Telemetry) error
	// Retrieve retrieves homing telemetry data from the specified repository.
	Retrieve(ctx context.Context, pm PageMetadata, filters TelemetryFilters) (TelemetryPage, error)
	// RetrieveSummary gets distinct countries and ip addresses
	RetrieveSummary(ctx context.Context, filters TelemetryFilters) (TelemetrySummary, error)
	// ServeUI gets the callhome index html page
	ServeUI(ctx context.Context, filters TelemetryFilters) ([]byte, error)
}

Service Service to receive homing telemetry data, persist and retrieve it.

func New

func New(repo TelemetryRepo, locSvc LocationService) Service

New creates a new instance of the telemetry service.

type Telemetry

type Telemetry struct {
	Services    pq.StringArray `json:"services,omitempty" db:"services"`
	Service     string         `json:"service,omitempty" db:"service"`
	Longitude   float64        `json:"longitude,omitempty" db:"longitude"`
	Latitude    float64        `json:"latitude,omitempty" db:"latitude"`
	IpAddress   string         `json:"-" db:"ip_address"`
	Version     string         `json:"magistrala_version,omitempty" db:"mg_version"`
	LastSeen    time.Time      `json:"last_seen" db:"service_time"`
	Country     string         `json:"country,omitempty" db:"country"`
	City        string         `json:"city,omitempty" db:"city"`
	ServiceTime time.Time      `json:"timestamp" db:"time"`
}

type TelemetryFilters

type TelemetryFilters struct {
	From    time.Time
	To      time.Time
	Country string
	City    string
	Version string
	Service string
}

type TelemetryPage

type TelemetryPage struct {
	PageMetadata
	Telemetry []Telemetry
}

type TelemetryRepo

type TelemetryRepo interface {
	// Save persists the telemetry event. A non-nil error is returned to indicate
	// operation failure.
	Save(ctx context.Context, t Telemetry) error

	// RetrieveAll retrieves all telemetry events.
	RetrieveAll(ctx context.Context, pm PageMetadata, filters TelemetryFilters) (TelemetryPage, error)
	// RetrieveSummary gets distinct countries, cities,services and versions in a summarised form.
	RetrieveSummary(ctx context.Context, filters TelemetryFilters) (TelemetrySummary, error)
}

TelemetryRepository specifies an account persistence API.

type TelemetrySummary

type TelemetrySummary struct {
	Countries        []CountrySummary `json:"countries,omitempty"`
	Cities           []string         `json:"cities,omitempty"`
	Services         []string         `json:"services,omitempty"`
	Versions         []string         `json:"versions,omitempty"`
	TotalDeployments int              `json:"total_deployments,omitempty"`
}