Documentation
¶
Overview ¶
Package event exposes some objects and utilities to get/set contextual information about an event. In a distributed architecture where events are flowing across internal services and third-party integrations, it is highly encouraged to pass an Event through a context.Context in order to trace them from end-to-end. helix.go core and integrations rely on Go contexts to manage logs and traces across services.
This package must not import any other package of this ecosystem.
Index ¶
Constants ¶
const Key string = "event"
Key is the key that shall be present in a JSON-encoded value representing an Event.
Example:
{
"key": "value",
"event": {
"name": "subscribed"
}
}
Variables ¶
This section is empty.
Functions ¶
func ContextWithEvent ¶
ContextWithEvent returns a copy of the context passed with the Event associated to it.
func ToFlatMap ¶
ToFlatMap returns a flatten map for a given Event. Keys are prefixed with "event.", and struct level are separated by a ".". All values are stringified.
This is primarily designed for the telemetry packages, allowing to pass contextual information about an event using Go's context or HTTP headers, but can be useful in some other use cases.
Example:
Event{
Name: "subscribed",
UserID: "user_2N6YZQLcYy2SPtmHiII69yHp0WE,
Params: url.Values{
"filters": []string{"a", "b", "c"},
},
Subscriptions: []Subscription{
{
ID: "sub_2N6YZQXgQAv87zMmvlHxePCSsRs",
CustomerID: "cus_2N6YZMi3sBDPQBZrZJoYBwhNQNv",
PlanID: "plan_2N6YZSE1SkWT9DrlXlswLhJ5K5Q",
},
},
}
Will produce:
map[string]string = {
"event.name" = "subscribed",
"event.user_id" = "user_2N6YZQLcYy2SPtmHiII69yHp0WE,
"event.params.filters[0]" = "a",
"event.params.filters[1]" = "b",
"event.params.filters[2]" = "c",
"event.subscriptions[0].id" = "sub_2N6YZQXgQAv87zMmvlHxePCSsRs",
"event.subscriptions[0].customer_id" = "cus_2N6YZMi3sBDPQBZrZJoYBwhNQNv",
"event.subscriptions[0].plan_id" = "plan_2N6YZSE1SkWT9DrlXlswLhJ5K5Q",
}
Types ¶
type App ¶
type App struct {
Name string `json:"name,omitempty"`
Version string `json:"version,omitempty"`
BuildID string `json:"build_id,omitempty"`
}
App holds the details about the client application executing the event.
type Campaign ¶
type Campaign struct {
Name string `json:"name,omitempty"`
Source string `json:"source,omitempty"`
Medium string `json:"medium,omitempty"`
Term string `json:"term,omitempty"`
Content string `json:"content,omitempty"`
}
Campaign holds the details about the marketing campaign from which a client is executing the event from.
type Cloud ¶
type Cloud struct {
Provider string `json:"provider,omitempty"`
Service string `json:"service,omitempty"`
Region string `json:"region,omitempty"`
ProjectID string `json:"project_id,omitempty"`
AccountID string `json:"account_id,omitempty"`
}
Cloud holds the details about the cloud provider from which the client is executing the event.
type Device ¶
type Device struct {
ID string `json:"id,omitempty"`
Manufacturer string `json:"manufacturer,omitempty"`
Model string `json:"model,omitempty"`
Name string `json:"name,omitempty"`
Type string `json:"type,omitempty"`
Version string `json:"version,omitempty"`
AdvertisingID string `json:"advertising_id,omitempty"`
}
Device holds the details about the user's device.
type Event ¶
type Event struct {
ID string `json:"id,omitempty"`
Name string `json:"name,omitempty"`
Meta map[string]string `json:"meta,omitempty"`
Params url.Values `json:"params,omitempty"`
IsAnonymous bool `json:"is_anonymous"`
UserID string `json:"user_id,omitempty"`
GroupID string `json:"group_id,omitempty"`
TenantID string `json:"tenant_id,omitempty"`
IP net.IP `json:"ip,omitempty"`
UserAgent string `json:"user_agent,omitempty"`
Locale string `json:"locale,omitempty"`
Timezone string `json:"timezone,omitempty"`
Timestamp time.Time `json:"timestamp,omitempty"`
App App `json:"app,omitempty"`
Campaign Campaign `json:"campaign,omitempty"`
Cloud Cloud `json:"cloud,omitempty"`
Device Device `json:"device,omitempty"`
Library Library `json:"library,omitempty"`
Location Location `json:"location,omitempty"`
Network Network `json:"network,omitempty"`
OS OS `json:"os,omitempty"`
Page Page `json:"page,omitempty"`
Referrer Referrer `json:"referrer,omitempty"`
Screen Screen `json:"screen,omitempty"`
Subscriptions []Subscription `json:"subscriptions,omitempty"`
}
Event is a dictionary of information that provides useful context about an event. An Event shall be present as much as possible when passing data across services, allowing to better understand the origin of an event.
Event should be used for data that you’re okay with potentially exposing to anyone who inspects your network traffic. This is because it’s stored in HTTP headers for distributed tracing. If your relevant network traffic is entirely within your own network, then this caveat may not apply.
This is heavily inspired by the following references, and was adapted to better fit this ecosystem:
- The Segment's Context described at: https://segment.com/docs/connections/spec/common/#context
- The Elastic Common Schema described at: https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html
func EventFromContext ¶
EventFromContext returns the Event found in the context passed, if any. If no Event has been found, it tries to find and build one if a Baggage was found in the context. Returns true if an Event has been found, false otherwise.
func EventFromJSON ¶
func EventFromJSON(input json.RawMessage) (Event, bool)
EventFromJSON returns the Event found at the "event" key in the JSON-encoded data passed, if any. Returns true if an Event has been found, false otherwise.
type Library ¶
type Library struct {
Name string `json:"name,omitempty"`
Version string `json:"version,omitempty"`
}
Library holds the details of the SDK used by the client executing the event.
type Location ¶
type Location struct {
City string `json:"city,omitempty"`
Country string `json:"country,omitempty"`
Region string `json:"region,omitempty"`
Latitude float64 `json:"latitude,omitempty"`
Longitude float64 `json:"longitude,omitempty"`
Speed float64 `json:"speed,omitempty"`
}
Location holds the details about the user's location.
type Network ¶
type Network struct {
Bluetooth bool `json:"bluetooth,omitempty"`
Cellular bool `json:"cellular,omitempty"`
WIFI bool `json:"wifi,omitempty"`
Carrier string `json:"carrier,omitempty"`
}
Network holds the details about the user's network.
type OS ¶
type OS struct {
Name string `json:"name,omitempty"`
Arch string `json:"arch,omitempty"`
Version string `json:"version,omitempty"`
}
OS holds the details about the user's OS.
type Page ¶
type Page struct {
Path string `json:"path,omitempty"`
Referrer string `json:"referrer,omitempty"`
Search string `json:"search,omitempty"`
Title string `json:"title,omitempty"`
URL string `json:"url,omitempty"`
}
Page holds the details about the webpage from which the event is triggered from.
type Referrer ¶
type Referrer struct {
Type string `json:"type,omitempty"`
Name string `json:"name,omitempty"`
URL string `json:"url,omitempty"`
Link string `json:"link,omitempty"`
}
Referrer holds the details about the marketing referrer from which a client is executing the event from.
type Screen ¶
type Screen struct {
Density int64 `json:"density,omitempty"`
Width int64 `json:"width,omitempty"`
Height int64 `json:"height,omitempty"`
}
Screen holds the details about the app's screen from which the event is triggered from.
type Subscription ¶
type Subscription struct {
ID string `json:"id,omitempty"`
TenantID string `json:"tenant_id,omitempty"`
CustomerID string `json:"customer_id,omitempty"`
PlanID string `json:"plan_id,omitempty"`
Usage string `json:"usage,omitempty"`
IncrementBy float64 `json:"increment_by,omitempty"`
Flags map[string]string `json:"flags,omitempty"`
}
Subscription holds the details about the account/customer from which the event has been triggered. It's useful for tracking customer usages.
Source Files