OSGi and Start Levels

OSGi and Start Levels

I’ve been working with OSGi for quite awhile and have recently been helping someone fight some start level issues. The problem turned out to be a misunderstanding of how start levels work in OSGi and its inspired me to write a little bit about how start levels work so others don’t repeat the same mistakes.

Let’s start with the basics first.

A start level is simply a non-negative integer value. The Framework has an ‘active start level’ that is used to decide which bundles can be started. Bundles themselves have an associated ‘bundle start level’ which is used to determine when a bundle is started. The bundles at a given start level will all have their start method completely executed before any bundles at a higher level are started. When booted, the Framework monotonically goes through each start level and starts relevant bundles (all the way until the active start level is met).

It’s also important to treat start levels as a management issue. In one system, a bundle could be running at start level 1 and in another system it could be at start level 42. This all depends on who is in control of deploying your bundle… so this means you shouldn’t worry about start levels at development time!

In the end, start levels are there to simply determine the start order of bundles.

Here are a few tidbits about start levels:

  • Start order within the start level is indeterminate!
  • The active start level is controlled by the ‘osgi.startLevel’ property and within Equinox, it defaults to a value of 6
  • A bundle start level of 0 is associated with the system bundle and can’t be changed

To illustrate things a bit better, let’s use a sample config from Equinox:



The following will be true about this particular configuration:

  • org.eclipse.equinox.common will start at startlevel 2 (via @2:start)
  • org.eclipse.core.runtime will start at startlevel 4 (via default value)
  • the framework startlevel will get set to 10

In Eclipse land, we’ve always had an interesting dance with start levels. For the longest time, we hid the whole concept from people. For example, the old Eclipse Application launch configuration looked like this:


In Eclipse 3.5, we updated the launch configuration to include information about start levels:


The main reason this was done was due to the introduction of OSGi Declarative Services (DS) in the Eclipse SDK. When working with OSGi services, having the ability to start bundles is important due to the life cycle of a OSGi service. An OSGi service is ONLY available when the bundle is in the ACTIVE state. If you were writing Eclipse-based applications and using OSGi services… not having access to set start level related information was painful. During the Eclipse 3.5 development cycle, we realized this and now have made it easier to tweak start level information. Besides launch configurations, here are some the other areas to set start level information that is more useful at deployment time:

p2 Touchpoint Actions (p2.inf)

You can place a p2.inf (in the root of a feature or within the META-INF directory of a bundle) file with touchpoint instructions to set the start level of a bundle (amongst various other things). An example p2.inf file may look like this if you wanted your bundle to be started:

instructions.configure =
       markStarted(started: true);

Product Definitions

Another way is to use product definitions. In Eclipse 3.5, we added support so you can specify start level information via the Configuration page:


This information can be used to generate proper p2 metadata so your bundles will have the right start level information when you go to deploy your product.

Ok, I think that’s enough of me talking about start levels. On the whole, when working with start levels, never depend on start order. Think about start levels as a management issue, not a development time issue.

Hope this helps!

  • Posted at 10:02 pm, June 10, 2009

    a great article – it will surely help people to understand start level better.
    for me the first rule about using start levels is:
    “Try to avoid setting of start-levels and let OSGI framework decide when to start a bundle”
    of course there are exceptions 😉
    * Logging: if you want to catch all log events from different log frameworks / log services then perhaps the bundle managing this should be started early – otherwise some log events could fall into a black hole
    * if DS need ConfigurationAdminService then the ConfigurationAdmin bundle must be started earlier then DS (bugzilla 276003)

  • Posted at 10:23 pm, June 10, 2009

    This feature will come in real handy for server side development, thanks 🙂

    @ekke: and also for any frameworks using the extender pattern, like Spring DM for example.


  • Wim Jongman
    Posted at 11:45 am, June 11, 2009

    Hi Chris,

    Thanks for the article. I have a question about the dynamics of DS. In the 3.5M6 New and Noteworthy there is this information:

    The Eclipse rich client platform now includes an implementation of OSGi declarative services (DS). This allows a lazy-starting plug-in to make OSGi services available to other plug-ins before it has been started.

    In your blog you state:

    An OSGi service is ONLY available when the bundle is in the ACTIVE state

    Can you elaborate on that a bit more?


    Wim Jongman

  • Posted at 8:28 pm, June 11, 2009

    Funny, just last night I noticed the start levels in the 3.5 release. Very nice. I don’t know much about Linux Kernel start levels, but it seems similar.

    Something that seems obvious, but merits asking: start levels and OSGI dependencies can totally screw up start levels if you are not careful, yes?

  • Posted at 12:26 am, June 12, 2009

    Great article,

    Cant wait for the new Eclipse to be finally released with P2.


  • Posted at 7:47 am, June 13, 2009

    Nice Article with important content,

    Yes, we in WSO2 also believe that a bundle should never depend on start levels. A bundle should be able to handle the dynamic behavior of OSGi services.

    In order to solve this problem, we have used OSGi Declarative Services (DS) extensively. That worked very well for us.