Forem: Chris Schmitz

Monitoring Browser Applications with OpenTelemetry

Chris Schmitz — Thu, 05 Sep 2024 21:00:40 +0000

Many development teams leverage OpenTelemetry (OTeL) on the server side to collect signals such as logs, traces, and metrics from their applications. However, what's often overlooked is the power of OTeL's browser instrumentation. This client-side observability data can provide meaningful insights and create a comprehensive view of an application's performance by connecting traces between the client and server.

What is OpenTelemetry?

OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior.

If you're interested in a deeper dive on OTeL, check out our recent article: What is OpenTelemetry and Why Should I Care?.

OpenTelemetry in Browser Applications

When it comes to browser apps, OpenTelemetry can provide valuable insights into:

Document Load Performance
User Interactions
Network Requests (XMLHttpRequest and Fetch)

These insights allow developers to identify bottlenecks, track user interactions, and monitor network requests without manual instrumentation. What's mentioned above is data you get relatively easily by leveraging OTeL's auto instrumentations but you can also add manual instrumentation to collect traces on any other code in you client-side apps.

Highlight and OpenTelemetry

Highlight's JavaScript SDK offers built-in support for collecting OpenTelemetry data from client-side applications. This integration allows you to seamlessly incorporate OpenTelemetry tracing into your web applications.

Enabling OpenTelemetry with Highlight

OTeL data collection is still in beta, so you need to explicitly enable it by setting the enableOtelTracing configuration option when initializing the SDK:

H.init({
  // ...
  enableOtelTracing: true
})

With this simple configuration, Highlight automatically collects most of the OpenTelemetry data you'll need by leveraging the auto instrumentations and doing some additional processing to make the data more useful in Highlight.

Connecting Client and Server Traces

One of the most powerful features of OpenTelemetry is the ability to connect traces across different services and environments. Highlight's SDKs facilitate this through context propagation, allowing you to create end-to-end traces that span from user interactions in the browser all the way to your backend services.

Here's how it works:

Trace Initiation: When a user interaction or a network request is initiated in the browser, the SDK creates a new span or continues an existing trace.
Header Injection: For outgoing HTTP requests (both XHR and Fetch), the SDK automatically injects trace context headers into the request. These headers typically include:
- traceparent: Contains the trace ID, parent span ID, and trace flags.
- tracestate: Carries vendor-specific trace information.
Server-Side Reception: The Highlight server-side SDKs extract these headers and continue the trace, linking the server-side spans to the client-side trace.
Trace Completion: As the request completes and returns to the client, the full trace, including both client and server spans, can be visualized in Highlight's UI.

This connection between client and server traces provides end-to-end visibility and is the link required necessary for page speed insights and client/server error correlation.

For server-side rendering where code executes on the server before HTML is sent to the browser, the trace context is propagated through a <meta> tag that is added to the HTML.

Example Client-Server Trace Lifecycle

Here's a simplified example of how this works in practice:

A user clicks a button in your web application.
The Highlight SDK creates a span for this user interaction.
This interaction triggers an API call to your backend.
The SDK automatically injects trace headers into this API call.
Your backend receives the request, extracts the trace context, and continues the trace.
The backend processes the request and sends a response.
The client receives the response and completes the span.

The result is a single trace that shows the complete journey of the request, from the initial user interaction in the browser, through your backend services, and back to the client.

Benefits

This connection between client and server traces provides several benefits:

End-to-End Visibility: You can trace a user's action all the way through your system, making it easier to diagnose issues and understand performance bottlenecks.
Performance Optimization: By seeing the complete picture, you can identify whether performance issues are occurring on the client-side, server-side, or in the network communication between them.
Error Correlation: If an error occurs, you can see the full context of what led to that error, including any relevant client-side actions or server-side processing.

By leveraging Highlight's OpenTelemetry integration, you can gain these insights with minimal configuration, allowing you to focus on improving your application's performance and user experience.

Handling Server-Initiated Traces

When a request for a page is made by fetching a new URL in the browser we don't have the JS SDK initialized in the browser until the server returns the HTML and renders the page, then fetches all the JS assets to render the app. In this case you pass the trace ID from the server to the client in a <meta> tag to handoff the trace initiated on the server to the client.

Here is an example of what the meta tag looks like in the browser:

<meta
  name="traceparent"
  content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01"
>

Note that the Highlight server SDKs often have helpers to create this tag. Here's an example using the Highlight Ruby SDK

<%= highlight_traceparent_meta %>

The browser OTeL instrumentation gathers timing information from window.performance.timing and creates spans for all the different timing events in the browser. This instrumentation parses the <meta> tag and associates all the spans it creates with trace data from the tag. This is illustrated in the screenshot of the flame graph below.

Here's how to parse what's going on in this flame graph:

The documentLoad span shows the full timing from submitting the URL in the browser to be loaded to having all the assets loaded and the page being fully interactive. The timing data for this span is gathered from window.performance.timing since we can't actually initiate a span before the JS loads.
The PagesController#home is the first span created on the server. You can trace the server code execution required to render the HTML that will be returned to the browser. When the HTML is returned to the browser the documentFetch span finishes.
After the HTML is loaded int he browser you can see the requests for the page's resources (all the JS and CSS files), these are the resourceFetch spans.

These resource timings provide a full picture of your app's load time, making it clear where the opportunities are to improve performance and provide a better UX.

Leveraging OpenTelemetry Data in Highlight

Collecting OpenTelemetry data is one thing, but gleaning actionable insights is another. You need some way of visualizing the data (like the flame graph shown above) in order to get actionable insights. Highlight exposes this data a few ways.

Viewing Traces in Highlight

When you open Highlight's UI, you'll find a dedicated section for traces. Here, you can see a list of all the traces collected from your application, including those that span from the browser to your backend services.

Trace List: This view provides an overview of all traces, typically sorted by timestamp. You can filter and search for specific traces based on various criteria such as duration, error status, or custom attributes.
Trace Detail View: Clicking on a specific trace opens a detailed view, showing the full journey of a request or user interaction. This view includes:
- A flame graph visualization of the trace, showing the hierarchy and timing of spans.
- Detailed information about each span, including start time, duration, and any custom attributes or events.
- For spans representing network requests, you can see details like HTTP method, status code, and headers.
Cross-Service Tracing: For traces that span from the browser to your backend services, you'll see a seamless view of the entire request lifecycle. This makes it easy to identify whether performance issues are occurring on the client-side, server-side, or in the network communication between them.

Analyzing Resource Timings and Web Vitals

Highlight's metrics product provides powerful tools for analyzing resource timings and Web Vitals, which are crucial for understanding and optimizing your application's performance.

Resource Timing Dashboard: This dashboard provides an overview of how long it takes to load various resources on your web pages. You can see:
- Load times for different types of resources (JS, CSS, images, etc.)
- Time spent on DNS lookup, TCP connection, TLS negotiation, and more for each resource
- Visualizations that help identify slow-loading resources or bottlenecks in the loading process
Web Vitals Metrics: Highlight tracks and displays key Web Vitals metrics, including:
- Largest Contentful Paint (LCP): Measures loading performance
- First Input Delay (FID): Measures interactivity
- Cumulative Layout Shift (CLS): Measures visual stability
- First Contentful Paint (FCP): Measures the time from navigation to when the browser renders the first bit of content
Performance Trends: Highlight allows you to track these metrics over time, helping you identify:
- The impact of code changes or deployments on performance
- Gradual degradations that might otherwise go unnoticed
- Improvements resulting from optimization efforts
Segmentation and Filtering: You can segment and filter these metrics based on various factors such as:
- Device type (mobile, desktop, tablet)
- Browser
- Geographic location
- Custom attributes you've defined

By combining the detailed trace data with these high-level performance metrics, you can get a comprehensive view of your application's performance. This allows you to quickly identify issues, understand their root causes, and measure the impact of your optimization efforts.

Conclusion

OpenTelemetry offers powerful tools for monitoring and optimizing browser applications. By leveraging Highlight's OpenTelemetry integration, developers can glean actionable insights with minimal configuration.

Whether you're dealing with client-side performance issues, server-side bottlenecks, or complex user journeys spanning multiple services, OpenTelemetry and Highlight provide the visibility you need to deliver exceptional web applications.

Building a Type-Safe Tailwind with vanilla-extract

Chris Schmitz — Thu, 27 Apr 2023 17:37:14 +0000

Tailwind CSS is a popular utility-first CSS framework that provides a great workflow for building UI. I encourage you to try it out if you haven’t already; there’s a reason it’s growing so quickly in popularity.

Although Tailwind has been a big step forward in many ways, it has always felt a little lacking in certain areas. One key issue is that there's no type safety, which can lead to referencing an incorrect value and not realizing it until runtime. Another problem I’ve seen is people getting lost in the sea of classes provided out of the box. Finally, building up the string of classes that need to be applied conditionally can get very messy.

We believe we’ve found a great middle ground to this by using vanilla-extract’s Sprinkles to build some utilities that can be used to generate and apply utility classes via a prop-based API (<Card pt={10}>…</Card> instead of <Card className="pt-10">...</Card>). This gives us complete control over our API out of the box to ensure we only introduce classes we need and ensures developers don’t accidentally apply a class that doesn’t exist. It also provides nice intellisense for prop names and values.

At a high level, our process for building this is:

Use design tokens to create a theme
Use our theme values to create a set of utility classes via Sprinkles
Package it up in a prop-based API via the Box component

Let’s dig into each aspect of this. You can play with and fork the code we go over in this article at https://stackblitz.com/edit/typesafe-tailwind.

Creating A Theme

We export our design tokens from Figma via Tokens Studio for Figma, then use those values to create a theme with vanilla-extract using createTheme. However, for this example, let’s start with something very basic that only captures a few basic tokens for background and text colors.

import { createTheme } from '@vanilla-extract/css';

import { createTheme } from '@vanilla-extract/css';

export const [themeClass, themeVars] = createTheme({
  backgroundColors: {
    primary: 'white',
    secondary: 'lightgray',
    brand: '#744ed4',
    good: 'lightgreen',
    bad: 'pink',
  },
  textColors: {
    default: 'black',
    secondary: 'gray',
    white: 'white',
    brand: '#744ed4',
    good: 'green',
    bad: 'red',
  },
  spaces: {
    auto: 'auto',
    '0': '0',
    '4': '4px',
    '8': '8px',
    '12': '12px',
    '16': '16px',
  },
});

This gives us two things:

A class string (themeClass) that can be applied somewhere near the top of our DOM tree. It ends up being a string that looks something like theme_themeClass__prfuqw0.
A “theme contract” (themeVars) which is an object that matches the structure of the object passed to createTheme, but the values are replaced with CSS variable names (e.g. bad: "var(--backgroundColors-bad__prfuqw5)".

The theme contract could actually be used to create another theme to enforce the new theme matches the shape of the existing theme, but we’ll save that for another article. For now, we can move on to creating our utility classes.

Create Our Utility Classes

The theme is useful, and you can probably see how you could quickly add support for theming and enforce the “contract” between all your themes thanks to createTheme. It’s a nice way of managing our design tokens in code, but we still need all of our utility classes which can apply these values as CSS properties. That’s where Sprinkles comes in 🧁

import { createSprinkles, defineProperties } from '@vanilla-extract/sprinkles';
import { themeVars } from './theme.css';

export const spaceProperties = defineProperties({
  properties: {
    margin: themeVars.spaces,
    marginTop: themeVars.spaces,
    marginRight: themeVars.spaces,
    marginBottom: themeVars.spaces,
    marginLeft: themeVars.spaces,
    padding: themeVars.spaces,
    paddingTop: themeVars.spaces,
    paddingRight: themeVars.spaces,
    paddingBottom: themeVars.spaces,
    paddingLeft: themeVars.spaces,
  },
  shorthands: {
    m: ['margin'],
    mx: ['marginLeft', 'marginRight'],
    my: ['marginTop', 'marginBottom'],
    p: ['padding'],
    px: ['paddingLeft', 'paddingRight'],
    py: ['paddingTop', 'paddingBottom'],
  },
});

export const colorProperties = defineProperties({
  properties: {
    backgroundColor: themeVars.backgroundColors,
    color: themeVars.textColors,
  },
});

export const sprinkles = createSprinkles(spaceProperties, colorProperties);

Using defineProperties and createSprinkles , we’ve just created a sprinkles utility that can be used to generate a class name string that can be passed down to our components. For example:

sprinkles({ px: 8, backgroundColor: 'good' })

Will generate a classname string that can be passed down to your DOM element’s class attribute:

sprinkles_paddingLeft_8__m095qc1m sprinkles_paddingRight_8__m095qc1a sprinkles_backgroundColor_good__m095qc1r

This already is useful if you want to use the sprinkles utility directly inside a stylesheet:

// button.css.ts
export const buttonClass = sprinkles({
    color: 'brand',
    px: '8',
    py: '4',
})

// button.tsx
<button className={buttonClass} onClick={...}>
    Click Me
</button>

You could also use sprinkles at runtime right inside a component:

// button.tsx
<button 
    className={sprinkles({
        color: 'brand',
        px: '8',
        py: '4',
    })} 
    onClick={...}
>
    Click Me
</button>

This already gives us a nice type-safe way of applying all our utility classes without needing to create stylesheets for each component. However, we didn’t like having to import sprinkles everywhere and still didn’t feel the UI was super intuitive. We wanted to provide a prop-based API for accessing the utility classes.

The `Box` Component

A common pattern in component libraries like MUI and Chakra is to create a Box component that wraps your utility classes and serves as the foundational building block for all other components.

You can probably imagine how we could pass props directly through to our sprinkles function from a prop (e.g. paddingTop="8" gets passed to sprinkles({ paddingTop: "8" }). However, declaring all these props and maintaining them by hand would be fairly tedious. Luckily, we can export the parameters of our sprinkles function as a type that can be used in the interface for our props! We just need to add the following line underneath where we define sprinkles:

export type Sprinkles = Parameters<typeof sprinkles>[0];

With this type we can make our Box component props interface.

import { Sprinkles } from './sprinkles.css';

export type BoxProps = React.PropsWithChildren &
  Sprinkles &
  Omit<React.AllHTMLAttributes<HTMLElement>, 'color'> & {
    as?: React.ElementType;
  };

Here we combine a few types to create props for all the attributes we could possibly want to pass through to the underlying elements:

React.PropsWithChildren - Basically just gives us the children prop.
Sprinkles - Covers all the props values that could be passed to sprinkles.
React.AllHTMLAttributes<HTMLElement> - A generic HTML attribute interface that covers all the standard DOM attributes we may want to pass down, like id, className, aria-*, etc. Note that we omit color because we want to control that with our utility classes.
The last type is custom, adding the as prop. This will allow us to render the component as any valid element type. e.g. as="button" or as="span".

Now we can write the component:

export const Box: React.FC<BoxProps> = ({ as = 'div', className, ...props }) => {
  const sprinklesProps: Record<string, unknown> = {};
  const nativeProps: Record<string, unknown> = {};

  Object.entries(props).forEach(([key, value]) => {
    if (sprinkles.properties.has(key as keyof Sprinkles)) {
      sprinklesProps[key] = value;
    } else {
      nativeProps[key] = value;
    }
  });

  return React.createElement(as, {
    className: clsx([sprinkles(sprinklesProps), className]),
    ...nativeProps,
  });
};

We iterate over all the props and check whether they can be passed to sprinkles. If they can, we put them into an object which is ultimately passed to sprinkles to create the class string for the component. We also accept a custom className which can apply additional classes. The rest of the props are put into a different object which is spread onto the underlying component as props.

One thing missing in our example is supporting ref. Let’s quickly add support for that via forwardRef. This gives us our final Box component code:

import React from 'react';
import clsx from 'clsx';
import { Sprinkles, sprinkles } from './sprinkles.css';

export type BoxProps = React.PropsWithChildren &
  Sprinkles &
  Omit<React.AllHTMLAttributes<HTMLElement>, 'color' | 'height' | 'width'> & {
    as?: React.ElementType;
  };

export const Box = React.forwardRef<unknown, BoxProps>(
  ({ as = 'div', className, ...props }, ref) => {
    const sprinklesProps: Record<string, unknown> = {};
    const nativeProps: Record<string, unknown> = {};

    Object.entries(props).forEach(([key, value]) => {
      if (sprinkles.properties.has(key as keyof Sprinkles)) {
        sprinklesProps[key] = value;
      } else {
        nativeProps[key] = value;
      }
    });

    return React.createElement(as, {
      className: clsx([sprinkles(sprinklesProps), className]),
      ref,
      ...nativeProps,
    });
  }
);

// Required because of forwardRef
Box.displayName = 'Box';

Adding Custom Styles

Using sprinkles and our Box component gives us most of what we need to build UI at Highlight. However, it’s inevitable that you’ll want to write some custom styles at some point, and vanilla-extract has you covered there as well.

You can use the style for creating a new hashed class name that can be imported and applied on a component just like you would normally write CSS, but with type safety and the ability to use your sprinkles in tandem with other custom CSS properties.

import { style } from '@vanilla-extract/css';

export const button = style([
    sprinkles({
        px: '4',
        py: '8',
    }),
    {
        outline: '2px solid currentColor'
    }
])

Or you can even apply styles globally for resetting styles or applying generic rules like font-family across your app:

import { globalStyle } from '@vanilla-extract/css';

globalStyle('body', {
  fontFamily: 'arial',
  margin: 0,
});

Using Recipes

One of the most common things we need to do in a component library is define a set of attributes for different variants of a component. For example, we want to have different sizes and colors for buttons. vanilla-extract makes this easy for us using Recipes.

Recipes allow us to provide some base styles for a component as well as combinations of styles that will be applied conditionally depending on which variant is being used. Here is a simple example for a Button component:

import { recipe, RecipeVariants } from '@vanilla-extract/recipes';
import { themeVars } from './theme.css';

export const button = recipe({
  base: {
    border: 0,
    borderRadius: 6,
  },

  variants: {
    kind: {
      primary: {
        background: themeVars.backgroundColors.brand,
        color: themeVars.textColors.white,
      },
      secondary: {
        background: themeVars.backgroundColors.secondary,
      },
    },
    size: {
      small: { padding: themeVars.spaces['4'] },
      medium: { padding: themeVars.spaces['8'] },
      large: { padding: themeVars.spaces['16'] },
    },
    rounded: {
      true: { borderRadius: 999 },
    },
  },

  defaultVariants: {
    kind: 'primary',
    size: 'medium',
  },
});

export type ButtonVariants = RecipeVariants<typeof button>;

Now we can take the button recipe and the ButtonVariants types to create our component.

import * as React from 'react';
import { Box } from './Box';
import * as styles from './Button.css';

type Props = React.PropsWithChildren &
  styles.ButtonVariants & {
    onClick: React.ButtonHTMLAttributes<HTMLButtonElement>['onClick'];
  };

export const Button: React.FC<Props> = ({ children, onClick, ...rest }) => {
  return (
    <Box as="button" onClick={onClick} className={styles.button(rest)}>
      {children}
    </Box>
  );
};

As we add more recipes they are automatically supported as props on the component. Usage would look something like this:

<Button size="small" kind="secondary" onClick={...}>Dismiss</Button>

Tradeoffs

While we clearly are fans of vanilla-extract, there are still some things we don’t like or feel could be improved in our usage. For example, we don’t have utility classes for things like hover or focus from sprinkles. Technically, we could add these with conditions, but we didn’t want to generate a lot of style rules that have a low probability of being used. We haven’t figured out a good way to clean up unused classes/styles, but we also generate a lot less of them since we are only adding what we need to the system when we need it.

One other consideration is the learning curve for vanilla-extract. Many people are familiar with Tailwind, but VE is not as mainstream and will require a little ramp up time for engineers to get used to. There’s more going on under the hood and you’ll need to add some configuration for your build tool as well.

Conclusion

We recognize vanilla-extract isn’t going to be right for everyone, but if you’re building a design system in TypeScript we think it’s worth a look. It’s helped us provide a great developer experience at Highlight and helped us iterate more quickly on our UI.

We only scratched the surface of vanilla-extract here, so check out the documentation if you’re interested in learning more. We’ll continue to share about how we are leveraging it to build the Highlight design system, and all our code is open source if you’re interested in exploring our usage more. All the code for the examples in this article are also available for anyone to fork and play around with as well.

We would love to hear about your experiences building component libraries. Please join us on Discord or hit us up on Twitter to chat more!

Forem: Chris Schmitz

Monitoring Browser Applications with OpenTelemetry

What is OpenTelemetry?

OpenTelemetry in Browser Applications

Highlight and OpenTelemetry

Enabling OpenTelemetry with Highlight

Connecting Client and Server Traces

Example Client-Server Trace Lifecycle

Benefits

Handling Server-Initiated Traces

Leveraging OpenTelemetry Data in Highlight

Viewing Traces in Highlight

Analyzing Resource Timings and Web Vitals

Conclusion

Building a Type-Safe Tailwind with vanilla-extract

Creating A Theme

Create Our Utility Classes

The Box Component

Adding Custom Styles

Using Recipes

Tradeoffs

Conclusion

The `Box` Component