Atlas

Atlas Help Center

Identifying bugs (or, equally importantly, determining that bugs 

 a part of a customer's problems) is an important part of resolving many support tickets. 

Traditionally, information about new bugs is locked away in error logs that are visible only to the engineering team. Atlas opens up access to these logs to support agents to help in diagnosing root problems so that faster short-term resolutions can be achieved for customers (ie, workarounds) and so that the engineering team can get directly to the core of issues where bugs are the root cause.

Below, we'll outline the steps for sending errors logged in Sentry to Atlas.

To connect Atlas to Sentry, login to your Sentry account and go to Settings > Integrations. Search for Atlas. Select the Atlas icon and then click "Accept and Install."

Without any changes to your code, Atlas will automatically attempt to match Sentry errors to specific customer timelines based off of the user_id and email for the customer. If that user is only in a single session, it will also show up in that session replay.

You can improve your experience further by linking Sentry issues to Atlas sessions (instructions below). Doing this will:

assign Sentry errors to the correct session for customers with multiple simultaneous sessions

assign Sentry errors to the correct customer if their data hasn't been shared with Sentry

Pass the Atlas session id to Sentry as the 

 tag. Make sure to get the session id right before your Sentry request since it can be changed over time. For example:

Sentry.init({
   dsn: "",
   release: "my-project-name@2.3.12",
})

Sentry.addGlobalEventProcessor((event) => {
	const sessionId = window.Atlas?.recording?.getSessionId();
	event.tags = {
		...(event.tags || {}),
		["atlasSupport.sessionId"]: sessionId,
		["atlasSupport.sessionUrl"]: sessionId
			? "https://app.getatlas.io/sessions/" + sessionId : "",
	};
	return event;
});

This depends on the frameworks and tools used. 

Send the Atlas session id to the backend with every request via cookie or header

 tag containing atlas session id in your Sentry setup code.

# Setting up Sentry 
import sentry_sdk
sentry_sdk.init(SENTRY_URL)

# On each request pass the user details and atlas session id to sentry as a tag
atlas_session_id = request.headers.get("X-Atlas-Session-Id")
sentry_sdk.set_tag("atlasSupport.sessionId", atlas_session_id)
sentry_sdk.set_user({"email": user.email, "id": str(user.id)})

If a Sentry error does not contain session id, Atlas will try to guess it (this will only works for logged in users with single active session).

For help with your specific setup, reach out to us at 

Sentry Integration

To configure the internal dashboard, set the URL to the URL of an individual customer in your internal tool (e.g. 

https://www.myapp.com/admin/user?user_id={user_id}/

You can use variables in the URL by wrapping them in curly brackets (e.g., 

). You can use the following variables in your URL:

In order for your internal dashboard to be visible within Atlas, the page needs to allow embedding. To check for this, ensure that the HTTP response from your server:

(if you are using cookie based authentication)

If this is not set correctly, you’ll see an error that looks like:

' because an 
ancestor violates the following Content Security Policy 
directive: "frame-ancestors 'self'".

 header via your application server. Here are some examples for some of the most common servers:

Header set Content-Security-Policy "frame-ancestors 'atlas.so';"

add_header Content-Security-Policy "frame-ancestors 'atlas.so';";

 to the end to ensure that nginx sends the header regardless of response code.

You can use the HTTP Response Headers GUI in IIS Manager or add the following to your web.config:

<system.webServer>
  <httpProtocol>
    <customHeaders>
      <add name="Content-Security-Policy" value="frame-ancestors 'atlas.so';" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

 header, you can extend it by adding value after semicolon (

 value, you can safely extend it by adding only 

If you are using cookie based authentication, then you will have to set the 

 attribute of the auth cookie to None so the cookie is accessible in Atlas UI.

from flask import Flask, make_response

app = Flask(__name__)

@app.route('/')
def hello_world():
    resp = make_response('Hello, World!');
    resp.set_cookie('same-site-cookie', 'foo', samesite=None);

Internal Dashboard

(for helpful background on what a custom event is, what its structure is, and how they are used in Atlas, see the Custom Events article)

 (CDP). You can consider a CDP to be a data hub where you send information in from various sources and back out to various destinations. Segment establishes a standard protocol for event types and structures so that it’s easier to add new sources and destinations, often without the need for any engineering work. They maintain a large collection of integrations to other tools, so that these connections from sources → Segment and from Segment → destinations are abstracted away from their users, leaving you the ability to focus only on the data you’re moving.

Atlas is currently integrated with Segment as a destination so that any events you currently have going into Segment can be sent to Atlas as custom events. Once the connection is established, you can manage how the events are shown in Atlas in the 

To set up Atlas as a destination in Segment:

, a code editor appears. Insert the following snippet of code in the editor:  

// Token is available at https://app.getatlas.io/configuration/integrations/segment
const SEGMENT_TO_ATLAS_TOKEN = '';

const BASE_URL = 'https://api.atlas.so';
const API_VERSION = 'v1';

async function onIdentify(event, settings) {
    const endpoint = `${BASE_URL}/${API_VERSION}/customers/upsert`;

    if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
    }

    if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
    }
    
    let firstName;
    let lastName;

    let fullName = event.traits.name;
    
    if (fullName) {
        firstName = fullName.split(' ')[0];
        lastName = fullName.substring(firstName.length).trim()
    } else {
        firstName = event.traits.firstName || event.traits.first_name
        lastName = event.traits.lastName || event.traits.last_name
    }

    const payload = {
        userId: event.userId,
        email: event.traits.email,
        firstName: firstName,
        lastName: lastName,
    };

    if (event.traits.phone) {
        payload['phoneNumber'] = event.traits.phone
    }

    if (event.traits.company) {
        const accountData = {
            name: event.traits.company.name,
            website: event.traits.company.domain,
            externalId: event.traits.company.id,
        };
        payload['account'] = accountData;
    }

    try {
        response = await fetch(endpoint, {
            method: 'POST',
            headers: {
                Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        if (response.status >= 300) {
            throw new RetryError(`Failed with ${response.status}`);
        }
    } catch (error) {
        throw new RetryError(error.message);
    }
}

async function onTrack(event, settings) {
    const endpoint = `${BASE_URL}/${API_VERSION}/events`;
    let response;

    if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
        return;
    }

    if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
    }

    const atlasEvent = {
        objectType: 'CUSTOMER',
        objectId: event.userId,
        name: 'Event Tracked',
        description: event.properties.title || '',
        payload: {
            ...event.context,
            ...event.properties
        }
    };

    try {
        response = await fetch(endpoint, {
            method: 'POST',
            headers: {
                Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(atlasEvent)
        });

        if (response.status >= 500 || response.status === 429) {
            throw new RetryError(`Failed with ${response.status}`);
        }
    } catch (error) {
        throw new RetryError(error.message);
    }
}

async function onPage(event, settings) {
    const endpoint = `${BASE_URL}/${API_VERSION}/events`;
    let response;

    if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
        return;
    }

    if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
    }

    const atlasEvent = {
        objectType: 'CUSTOMER',
        objectId: event.userId,
        name: 'Page Viewed',
        description: event.properties.title || '',
        payload: {
            ...event.context,
            ...event.properties
        }
    };

    try {
        response = await fetch(endpoint, {
            method: 'POST',
            headers: {
                Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(atlasEvent)
        });

        if (response.status >= 500 || response.status === 429) {
            throw new RetryError(`Failed with ${response.status}`);
        }
    } catch (error) {
        throw new RetryError(error.message);
    }
}

async function onGroup(event, settings) {
  const endpoint = `${BASE_URL}/${API_VERSION}/accounts/upsert`;

  if (!event.userId) {
    throw new EventNotSupported("Mandatory parameters are missing");
  }

  if (!SEGMENT_TO_ATLAS_TOKEN) {
    console.log("Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing");
    return;
  }

  const payload = {
    externalId: event.groupId,
    name: event.traits.name,
    email: event.traits.email,
  };

  try {
    response = await fetch(endpoint, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });
    if (response.status >= 300) {
      throw new RetryError(`Failed with ${response.status}`);
    }
  } catch (error) {
    throw new RetryError(error.message);
  }
  
}

The API Key and the APP ID are available on the Atlas dashboard at -

Once your code is saved, you can test it by grabbing a Sample Event from the events you have already brought into Segment:

And you can verify the connection was successful in Atlas by going to the 

App Configuration > Integrations > Segment

(note: depending on how often you have events sent to Segment, this may take some time)

Introduction and instructions for setting up connection with Segment