react-tracing

    0.1.5 • Public • Published

    📈 React Tracing Build Status Coverage Status Greenkeeper badge All Contributors FOSSA Status

    Goal

    react-tracing enables React and React Native developers to build faster products by making the real-world performance visible. Although it is optimized for React and React Native we also support pure JS.

    For this we want to use well-known tooling from the backend world and bring it to the frontend, so that engineering teams might gain a better understanding where a loading time improvement might help the most.

    Imagine having graphs like this showing real users using your (web-)app when you want to decide which performance issue to tackle next:

    Introduction

    Terminology

    This section aims to give you a small overview into the language used in opentracing

    Term Description
    span a single operation that is traced
    child span like functions calls are nested, spans can be, too

    How we manage your spans

    In other tracing solutions you have to define which span is the child of which, but react-tracing handles this for you. Therefore react-tracing uses a stack, making use of Javascripts Single-Threadedness, to determine which spans should rely on each other. This stack is stored in the global scope (it's a bit ugly, do you have a better idea?) under window.reactTracing.stack or global.reactTracing.stack.

    Supported Tracing Implementations

    We can use every opentracing solution in general, but currently there is only one, therefore it is not configurable yet. As soon as there are other solutions we will add them here.

    Working with multiple systems

    Every time you send a fetch or xhr request with react-tracing's instrumented versions of them the X-B3-TraceId, X-B3-SpanId HTTP headers are set, so that your server can pick the span up and extend the tracing context.

    Environment Setup

    You need a Zipkin instance running on an accessible server. For development puropses you can start one with docker: docker run -d -p 9411:9411 openzipkin/zipkin

    Usage

    import Tracing from "react-tracing";
    const tracer = new Tracing({
        serviceName: "Frontend",
        endpoint: "http://localhost:9111",
        kind: "client", // default
    });
     
    // TRACKING HTTP REQUESTS
    // ======================
     
    // You have two options here depending on your style of usage
    // a) You can either use it locally, enabling you to set a different service name per fetch
    const defaultFetch = tracer.fetch();
    const tracingXhr = tracer.xhr({ XMLHttpRequest }); // last param optional, otherwise a global is used
     
    // b) You can choose to let us handle everything for you
    // This mutates the global fetch and XHR request
    tracer.initGlobalNetworkTracer();
     
    // You can define a span that generates you the span names, this is the default one.
    // If you want to use the default and a third param pass anything that is not a function as the second parameter.
    const getSpanName = ({ url, method, body }) => `${url}-${method}`;
    const tracedFetch = tracer.fetch({ getSpanName, fetch});
     
     
     
    // TRACKING USER ACTIONS
    // =====================
     
    // You can use it in React
    const Link = tracer.component("a")
     
    // You can use it in React Native
    const Touchable = tracer.component(TouchableHighlight);
     
    // Every onPress / onClick / onLongPress is wrapped with a function like this
    // If a promise is returned, the span will end once it resolves or rejects
    const clickHandler = function() {
        return fetch("http://foo.de").then(...);
    };
    const tracedClickHandler = tracer.wrap(clickHandler);
     
    // Usage in the component
    const MyTracedComponent = () => (
      <Touchable
        tracingName="create-new-order"
        // Either use static additional infos
        tracingInfo={{
          buttonLabel: 'ClickMe',
          userId: 42,
        }}
        // Or use dynamic ones
        tracingInfo={e => ({
          clickPosition: e.targetX,
        })}
        {...usualProps}
      >
        <Text>ClickMe</Text>
      </Touchable>
    );
     
     
     
    // ADD YOUR OWN TRACING
    // ====================
     
    function myVeryLongFunction() {
      tracing.startSpan("Long Function");
      asyncFunction().then(() => {
         tracing.startSpan("Synchronous Bitcoin Mining");
         try {
          mineBitcoinsAndDonateThem();
         } catch(e) {
           // Something went wrong, let's log the error
           tracing.log({
             miningError: e
           });
         }
         tracing.finishSpan();
      }).finally(() => {
        tracing.finishSpan();
      });
    }

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Daniel Schmidt

    💻 📖 🤔 ⚠️ 🔧 💡

    Daniel Banck

    📖 🤔

    Raphael Randschau

    🤔

    This project follows the all-contributors specification. Contributions of any kind welcome!

    License

    FOSSA Status

    Install

    npm i react-tracing

    DownloadsWeekly Downloads

    0

    Version

    0.1.5

    License

    MIT

    Last publish

    Collaborators

    • dschmidt