# Log your first custom event

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Custom events record the user actions you care about, and Statsig turns them into metrics for web analytics, product analytics, and experimentation. Log an event with the `logEvent` API in any Statsig client or server SDK. You can then view the event in [Metrics Explorer](https://docs.statsig.com/product-analytics/overview), turn it into [custom metrics](https://docs.statsig.com/metrics/how-metrics-work), visualize it in [dashboards](https://docs.statsig.com/product-analytics/dashboards), or use it in [experiment results](https://docs.statsig.com/metrics/pulse) to show the impact of your experiments.

Statsig provides several ways to get started:

1. Statsig web SDKs offer [autocaptured web analytics](https://docs.statsig.com/webanalytics/overview) to automatically log common events like pageviews, clicks, and more.
2. Statsig offers [integrations](https://docs.statsig.com/integrations/introduction) to connect your existing event data in Segment, mParticle, and other sources.
3. All Statsig client and server SDKs provide a simple `logEvent` API to instrument your own events in your app or webserver.

For general guidance on event logging and core concepts, continue reading or go to the "Logging events through SDKs" section.

## Identifying users with the StatsigUser object

Many analytics platforms have a concept of "identifying" a user. In Statsig, the `StatsigUser` object represents this concept. You set the `StatsigUser` object at initialization time in client SDKs, or with each event in server SDKs.

The [`StatsigUser`](https://docs.statsig.com/sdks/user) is a set of properties that describe the user. The JSON definition is consistent across all SDKs and integrations:

#### StatsigUser Object

```json
{
  "userID": "123",
  "customIDs": {},
  "email": "user@example.com",
  "ip": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "country": "US",
  "locale": "en-US",
  "appVersion": "1.0.0",
  "custom": {},
  "privateAttributes": []
}
```

Statsig reserves the `userID` field for a unique identifier for the user. Use the ID of the logged-in user.

The Group analytics section explains `customIDs`.

The other fields support targeting and evaluation for feature flags, and you can also use them for custom metrics and data queries in Metrics Explorer.

## Group analytics

Another core concept in analytics is grouping. A user can belong to a company, organization, page, or other entity.

In Statsig, the `customIDs` field represents groups. It's a dictionary that can contain multiple IDs for a single user. For example, a user can have the following `customIDs`:

#### Group Example

```json
{
  "userID": "123",
  "customIDs": {
    "companyID": "456",
    "projectID": "abc"
  }
}
```

Statsig computes all metrics at the user level and also for each custom identifier. This means you can run experiments at a company level, where all users in a company receive the same experience, and compare the impact on company-level metrics.

You can also use Metrics Explorer to slice metrics at the company level rather than the user level, if you have configured a `customID` for the group. For example, the Statsig project can display console page views at a user or company level:

![Viewing Console Page Views at a User Level](https://docs.statsig.com/images/guides/logging-events/67719f66-63cb-41c7-8d83-d2a567738a84.png)

To set up a new "group" or "customID":

1. Go to your [project settings](https://console.statsig.com/settings).
2. Locate the "Custom IDs" section and hit "edit".

![CustomIDs in project settings](https://docs.statsig.com/images/guides/logging-events/e26cc341-13c2-4b78-898f-02d56bfc2474.png)

3. Name the new `customID` and add a description so other members of your project understand its purpose.
4. Start logging events with that customID in the `customIDs` field of the StatsigUser object.

> **Note:**
>
> You must provide the set of all IDs on each StatsigUser object.

## Best practices

### Set all known IDs on each StatsigUser object

To generate metrics for each user and group, Statsig requires all IDs on each `StatsigUser` object. Pass all identifiers for the user at client SDK initialization time or when calling `logEvent` in a server SDK, so each identifier contributes to the correct metrics.

If you use a logged-out identifier for anonymous users, continue passing that identifier after the user logs in and you populate `userID`. Passing the logged-out identifier after login lets gates or experiments targeting that identifier continue bucketing the user correctly. It also lets Statsig calculate metrics at both the logged-out and logged-in levels.

### Deduplicating custom events

Statsig doesn't provide a way to deduplicate custom events that you log.

### Naming conventions

Consistency is the most important aspect of event naming. An inconsistent events catalogue becomes difficult to navigate. Statsig accepts any naming convention (for example, `Page View`, `PageView`, `Page-view`, or `page_view`), but the recommended format is `page_view`: lowercase, no spaces. You can't use special characters in event names. Statsig drops events that contain the following character set: `"\\[\]{}<>#=;&$%|\u0000\n\r"`. Using the recommended convention avoids duplicate entries with different casing and ensures compatibility with downstream systems connected through integrations.

### What to measure

For experimentation and product analytics, log events that correspond to user actions. How you classify events depends on your goals:

1. Avoid high-cardinality event names if you have a small user base, because sparse data reduces the reliability of metrics. For example, an eCommerce website should use a generic `product_page_view` event rather than a separate event name for every product page. Store contextual page information in the `optional_event_metadata` object.
2. If you have a well-defined user funnel, log each step as a separate event.
3. If you have a less defined user journey, log generic events (for example, `page_view`) and add more detail to the value field (the primary dimension of interest) or the `optional_event_metadata` object.

## Logging events through SDKs

All Statsig SDKs provide an API to log events. The API looks like this:

#### JavaScript

```js
statsig.logEvent(
  event_name,
  optional_event_value,
  optional_event_metadata
);
```

Where event name describes a notable event in your product, like `sign_up`, `achievement_unlocked`, `add_to_cart`, `check_out`, etc.

Events can optionally include an event value: for example, the type of achievement unlocked, the name of the product added to cart, or the price of the item purchased. In experiments, the value field generates an automatic breakdown of the event when there are fewer than 8 distinct values.

The metadata field lets you specify additional details about the event. The following examples show how a `logEvent` call looks:

#### JavaScript Example

```js
statsig.logEvent(
  'add_to_cart', // Name
  19.99, // Price
  {
    item_id: 'BC22010',
    cart_size: '2',
    user_segment: 'first_time_purchaser',
  }
);
```

#### C# Example

```csharp
StatsigClient.LogEvent(
  "level_completed", // Event Name
  11, // Level number
  new Dictionary<string, string>()
  {
    { "score", "452" }
  }
);
```

> **Info:**
>
> **Size limits on event payload** There are limits to how large each event field can be:
>
> | Field type | Limit |
> | --- | --- |
> | Object fields | 4096 (stringified length) |
> | String fields | 64 (length) |

Refer to the [SDK reference](https://docs.statsig.com/sdks/getting-started) for more details on logging events in your language.