Blackfire is now an official oEmbed provider; it allows anyone to embed shiny profile graphs in blog posts.

A few weeks ago, @dunglas asked us to add an oEmbed endpoint to ease graph integration in blog posts

@blackfireio feature request: adding an oEmbed endpoint to allow integrating profiles in blog posts and on social networks would be so cool!

— Kévin Dunglas (@dunglas) August 25, 2015

We looked into this format and we implemented it.

What is oEmbed?

From the website itself:

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

Being an oEmbed provider means that we provide an API endpoint to fetch embedded content. In the case of Blackfire, we provide content for profile call graphs.

Querying an oembed endpoint is trivial and, as described in the specification, it can be done easily via cURL:

curl https://blackfire.io/oembed?maxwidth=300&url=https%3A//blackfire.io/profiles/8c3d9297-231c-42ea-889c-6c3c98036c13/graph

The endpoint returns a JSON payload like the following:

{
    "version": "1.0",
    "type": "rich",
    "html": "<iframe frameborder=\"0\" allowfullscreen src=\"https://blackfire.io/profiles/8c3d9297-231c-42ea-889c-6c3c98036c13/embed\" width=\"300\" height=\"225\"></iframe>",
    "width": 300,
    "height": 225,
    "author_name": "Romain Neutron",
    "provider_name": "Blackfire.io",
    "provider_url": "https://blackfire.io/",
    "title": "Welcome!"
}

These data are quite nice because it allows you to embed a graph alongside a blog post using the “html” property of the JSON payload.

Blackfire endpoint

The Blackfire enpoint is available at https://blackfire.io/oembed and allows you to embed public profiles and public comparisons. This means you cannot embed private graphs, only public ones.
Blackfire provides an auto-discovery mechanism for oEmbed consumers. This autodiscovery is done via <link> tags in the graph HTML meta.

How to focus on a node/dimension?

To embed a profile, share it publicly, then select the dimension and call you want to focus on. Here, we select the CPU dimension and we focus on spl_autoload_call:

Once you’re done, use the full URL and its query-string on the oEmbed endpoint. In case you’re using Wordpress, ensure you’ve configured it the proper way (see next paragraph), and paste the URL into the blog post.

WordPress configuration

In order to be able to use this auto-discoverability feature on WordPress, enable the oEmbed Discovery Plugin. You can also customize the size of the graph in the functions.php file of your WordPress theme:

function change_embed_size($dimensions = null, $url = null) { 
    // Adjust values 
    if (0 === strpos($url, 'https://blackfire.io/profiles/')) { 
        return array('width' => 750, 'height' => 450); 
    } 

    return $dimensions; 
} 

add_filter('embed_defaults', 'change_embed_size', 10, 2);

Happy sharing!